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#* Comment ** 



Commands are shown in CAPITAL LETTERS. The names must con- 
tain no blanks and be delimited by a non -alphabetic character 
(usually a blank). 

Literal keywords, which are entered optionally but exactly as 
specified, appear in CAPITAL LETTERS . 

Required parameters, for which you must substitute a value, ap- 
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in standard italics. 

An element inside brackets is optional. Several elements stacked in- 
side a pair of brackets means the user may select any one or none of 
these elements. 
Example: [ A ] 
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c c 
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t ) indicates a terminal key. The legend appears inside. 

Programmer's comments in listings appear within << >> . 
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PREFACE 



This manual documents the system -supplied intrinsics available with MPE (Multi- 
Programming Executive) on the HP 3000. It documents the intrinsics on the MPE V 
operating system and includes all changes and enhancements through the G.02.00 release 
of MPE. To assist you in locating information, a brief description of each section in this 
manual follows : 



Section I 



INTRODUCTION TO MPE INTRINSICS 

An overview of MPE V intrinsics , how to invoke them , their functions , 
and the optional capabilities required by system users to perform selec- 
ted functions. 



Section II INTRINSIC DESCRIPTIONS 

A detailed description of all MPE intrinsics, including the syntax, 
parameters, and condition codes for each. When applicable, functional 
returns, special considerations, and references to additional sources of 
information are included. The FLABELINFO, FPARSE, LOG INFO, and 
GET INFO intrinsics are new effective with the G.02.00 release of MPE. 
They are documented in this section. 

Section III OPTIONAL CAPABILITIES 

MPE functions which must be performed by users with specifically as- 
signed optional capabilities. 

Section IV ACCESSING AND ALTERING FILES 

Background information on the MPE file system , including descriptions 
of some typical file -related operations performed with MPE intrinsics. 

Section V OTHER APPLICATIONS OF MPE INTRINSICS 

How to perform the various functions available to users with MPE in- 
trinsics. Examples of program dialogs are included for reference. 

Appendix A MPE DIAGNOSTIC MESSAGES 

The different types of interactive messages you might encounter while 
using MPE intrinsics. 

Appendix B DEVICE CHARACTERISTICS 

Details on how to alter the operation of specific peripheral devices using 
MPE intrinsics. The characteristics of several types of devices including 
terminals , printers , card readers , and magnetic tape are discussed . 

This manual replaces the First Edition of the MPE V Intrinsics Manual (32033-90007). 
Some additional sources of information you might find helpful include : 

• MPE V System Operation and Resource Management Reference Manual 
(32033-90005). 

• MPE V Commands Manual (32033-90006). 

• MPE V Utilities Reference Manual (32033-90008). 

• MPE File System Reference Manual (30000-90236). 
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Many programs use procedures or subroutines to handle recurring tasks. In the Multi -Programming 
Executive (MPE, the HP 3000 operating system), many of these tasks are performed through a set of 
system -supplied procedures known as intrinsics. Since these intrinsics must always be available to 
MPE, they are also always available to any process on the system (a process is the basic executable en- 
tity in MPE). A process is not a program itself, but the unique execution of a program by a par- 
ticular user at a particular time . 

Most intrinsics are coded in SPL/3000 (Systems Programming Language for the HP 3000 Computer 
System) and are defined by a procedure declaration consisting of: 

• A procedure head, containing the procedure name and type, parameter definitions, and other in- 
formation about the procedure. 

• A procedure body, containing executable statements and declarations local to this procedure. 

As part of their function, several intrinsics also return values to the processes that invoke them. 
These intrinsics are called type procedures. 

Intrinsics are no different from procedures you may write yourself , except that the code is invisible to 
you, and they are declared (in SPL) with the INTRINSIC statement rather than the PROCEDURE 
statement. 



INTRINSIC CALLS 

Intrinsic calls programmatically invoke MPE intrinsics (that is, from within a program). In SPL 
programs (refer to "Calling Intrinsics From SPL" in this section) , you can write the intrinsic calls ex- 
plicitly or through procedure statements. Some languages, such as BASIC, COBOLII, FORTRAN, 
and Pascal, allow the option of directly calling MPE intrinsics. Within these languages the compiler 
will make calls to the intrinsics for you when you use input/output statements of the languages. 
Other languages such as APL, COBOL, and RPG will not allow direct calls. Within these languages 
intrinsic calls must be made through a subroutine written in a language that allows direct calls or 
through language commands that do the calls for you. 

All MPE intrinsics are treated as external procedures by user programs. External linkages from user 
programs are satisfied when the user programs are segmented (via the : PREP command) and allocated 
residence in memory (at :RUN time). Refer to the MPE Segmenter Reference Manual 
(30000-9001 1) for a discussion of segments, segmentation, and allocation. 

Calling Intrinsics From SPL 

Before an intrinsic can be called from an SPL program, it must be declared at the beginning of the 
program. The intrinsic can be declared in the same manner as any other SPL procedure or in an in- 
trinsic declaration statement. 
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PROCEDURE DECLARATIONS. To declare an intrinsic as an SPL procedure add the EXTERNAL 
option to the procedure head and delete the procedure body. The EXTERNAL option means that the 
procedure body (code) is linked to the main program by the operating system after compilation. An 
example of calling the DBINARY intrinsic as a procedure follows: 

**HEAD** 

double **TYPE** 

PROCEDURE DBINARY **NAME** 

Cdval, string, length); **FORMAL PARAMETERS** 

value length; **VALUE PART** 

double dval; **SPECIFICATION PART** 

byte array string; 

integer length; 

option external; **0PTI0N PART** 

**B0DY** 

INTRINSIC DECLARATIONS. Writing the complete head for some intrinsics can be very time- 
consuming, so a shortcut is provided in SPL/3000. Since SPL/3000 provides no construct for input 
and output, it provides a simple interface for intrinsics. This interface is the INTRINSIC declaration. 
The INTRINSIC declaration can be used with any system -known intrinsics defined in this manual 
The format of the INTRINSIC declaration statement is: 

INTRINSIC intrinsioname ,intvinsicname , . . . ,intrinsioname ; 

In the intrinsicname list, you name all intrinsics to be called within your program. When more than 
one intrinsic is named, the names must be separated by commas. For example, to use the INTRINSIC 
declaration statement to declare the FOPEN, FREAD, FWRITE, and FCLDSE intrinsics, enter: 

I NTR I NS I C FOPEN , FREAD , FWR I TE , FCLOSE ; 

Regardless of whether an intrinsic is declared as a procedure or in an INTRINSIC declaration state- 
ment, you must know the number and type of parameters the intrinsic uses in order to call it correct- 
ly. Parameters can be passed to a procedure (intrinsic) either "by reference" or "by value". When a 
parameter is passed by reference, its address in the caller's data area is made available to the called 
procedure. If the variable is changed by the called procedure, the storage in the caller's data area is 
updated. When a parameter is passed by value, the called procedure receives a local (private) copy of 
the actual data value. If the called procedure changes this private copy, the corresponding variable in 
the calling routine remains unchanged. 

IMPLEMENTING INTRINSIC CALLS. You call an intrinsic in your program exactly as you would 
call any SPL procedure, by entering the intrinsic name, followed by a parameter list enclosed in 
parentheses. These parameters must follow the positional format shown in each intrinsic description 
in Section II and must be separated by commas. For example, a call to the FREAD intrinsic could be 
written as: 

FREAD(FN,TAR,TC); 

If the Option Variable notation (0-V) appears in the intrinsic syntax as shown in Section II, some of 
the intrinsic parameters are optional. However, since all intrinsic parameters are positional, you 
must indicate a missing parameter within a parameter list by omitting the parameter itself', but 
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retaining the preceding and following commas. For example, if the second parameter of an FOPEN 
call is omitted , you would write : 

F0PENCFILENAME,,3); 

When the first parameter is omitted from a list, this is indicated by following the left parenthesis 
with a comma. Omitting one or more parameters from the end of a list is indicated by simply writing 
the terminating right parenthesis after the last parameter . 

Input parameters , in some intrinsic calls , are passed to the intrinsic as words whose individual bits or 
fields of bits signify certain functions or options. Bit (0:1) is the high order (that is, most sig- 
nificant), left-most bit. Throughout this manual, bit groups are denoted using the standard SPL 
notation. Thus, bits (13:3) indicates bits 13, 14, and 15. In cases where some of the bits within a 
word are described in this manual as "reserved for MPE", you are advised to set such bits to zero. 
This will help ensure the compatibility of your current program with future releases of MPE. 

Output parameters, in some cases, are passed by an intrinsic to words referenced by a calling 
program. Bits within these words described as "reserved for MPE" are set to zero by the system unless 
otherwise noted in the discussion of the particular parameter. 

To call an intrinsic from an SPL program , follow the steps listed below : 

1 . Refer to the intrinsic description in Section II to determine the parameter types and their posi- 
tions in the parameter list. 

2. Declare variables or arrays to be passed as parameters, by type, at the beginning of the 
program . 

3 . Include the name of the intrinsic in an I NTR I NS I C declaration statement . 

4. Issue the intrinsic call at the appropriate place in your program. 

For example , the description of the PR I NTOP intrinsic is shown in Section II as : 

LA IV IV 

PR I NTOP (massage , length ^control ) ; 

The bold italics used for message, length, and control signify that these are required para- 
meters. (Optional parameters are signified by standard italics.) 

The mnemonics LA, IV, and IV over message, length, and control denote logical array (para- 
meters are logical unless otherwise specified), integer by value, and integer by value, respectively. 
Refer to the beginning of Section II for a description of all mnemonics. 

The array name to be used as the message parameter must be declared as an array at the beginning of 
the program. Similarly, the variables for length and control must be declared as integers. 

Figure 1-1 shows the intrinsic PR I NTOP being called from an SPL program after being declared with 
the INTRINSIC declaration statement. MESSAGE is an array, and the variables LENGTH and CONTROL 
are integers. The percent sign (%) means the value (60) is to be treated as octal. The string is treated 
as a decimal value if it begins with a plus sign, a minus sign , or a number. 

Figure 1-2 shows the same intrinsic being called with numeric values instead of symbolic identifiers 
being specified for the parameters length and control. 
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$ CONTROL USLINIT 

<< USING THE INTRINSIC DECLARATION STATEMENT » 
BEGIN 

ARRAY MESSAGE CO: 9) :="MESSAGE TO OPERATOR "; 

I NTEGER LENGTH , CONTROL ; 

INTRINSIC PRINTOP; 

LENGTH: =10; 

CONTROL : =%60 ; 

PR I NTOP (MESSAGE , LENGTH .CONTROL ) ; 
END. 



Figure 1 - 1 . Calling the PRINTOP Intrinsic from SPL 



$CONTROL USLINIT 

« USING NUMERIC VALUES AS PARAMETERS » 
BEGIN 

ARRAY MESSAGE(0:9):="MESSAGE TO OPERATOR "; 
INTRINSIC PRINTOP; 
PRINTOP(MESSAGE,10,X60); 
END. 



Figure 1 - 2 . Using Numeric Values as Parameters in an Intrinsic Call 



Calling Intrinsics From Languages Other Than SPL 

Direct calls to intrinsics are allowed in some languages. These languages include BASIC, COBOLII, 
FORTRAN, and Pascal. To implement a call in these languages follow the steps used for calling an 
intrinsic from SPL. APL, COBOL, and RPG do not allow direct calls; to call an intrinsic from these 
languages you must call the intrinsic through a subroutine written in a language that allows direct 
calls. Additionally since most intrinsics are written in SPL, when a call is made from a program not 
written in SPL, careful consideration must be taken to ensure proper mapping of data types. Table 
1 - 1 provides a listing of compatible data types between the languages that allow direct intrinsic calls 
and SPL. For more information on calling intrinsics from languages other than SPL refer to the ap- 
propriate language reference manual. 
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Table 1 - 1 . Compatible Data Types 



SPL 


BASIC 


COBOLII 


FORTRAN 


PASCAL 


Integer 


Integer 


Computational 


Integer/ 


Defined in the range 






1-4 Digits 


Integer*2 


-32768. .32767 


Logical 


No Equivalent 


Display 


Logical 


Boolean, or defined in 
the range -32768. .32767 


Byte 


String (x$) 


Display 


Character/ 
Characters 


Char 


Double 


No Equivalent 


Computational 
5-9 Digits 


Integer*4 


Integer 


Real 


Real 


No Equivalent 


Real 


Real 


Long 


Long 


No Equivalent 


Long 


Long real 



INTRINSIC CALL ERRORS 

Some intrinsics alter the "condition code" which is stored in two bits (6:2) in the Status Register. 
These two bits have four states which are assigned as follows : 

00 Is CCG, or Condition Code Greater Than (>). 

01 Is CCL, or Condition Code Less Than (<). 

1 Is CCE, or Condition Code Equal (=). 

1 1 Undefined. 

Since bits (6:2) of the Status Register are affected by many instructions, check for condition codes 
immediately upon return from an intrinsic, as in the "IF" statements in Figure 1-3. A condition 
code is always CCG, CCL, or CCE, and has the general meaning indicated below. The specific mean- 
ing depends upon the intrinsic called (refer to Section II for a description of these meanings). For a 
more detailed discussion of condition codes, refer to the Machine Instruction Set Reference Manual 
(30000-90022). 



Condition Code State SPL Branch Word 
CCE 

CCG > 



General Meaning 

Condition Code Equal. This generally indicates that the 
request was granted . 

Condition Code Greater Than. A special condition oc- 
curred, but may not have affected the execution of the 
request. (For example, the request was executed, but 
default values were assumed as intrinsic call 
parameters.) 
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Condition Code State SPL Branch Word General Meaning 

CCL < Condition Code Less Than. The request was not grant- 

ed , but the error condition may be recoverable . Beyond 
this condition code, some intrinsics provide additional 
error information to the program through their return 
values or reference parameters . 

Two types of errors may occur when an intrinsic is executed . The first , denoted by the CCG or CCL 
condition codes, is generally recoverable (control returns to the calling program), and is known as a 
condition code error. The second type is an abort error, which occurs when a calling program passes 
illegal parameters to an intrinsic, or does not have the capability demanded by the intrinsic. An 
abort error terminates the calling process. 

"Soft interrupts" are interrupts generated by software events, where the CPU is interrupted from 
processing and the operating system switches execution to an interrupt procedure. This sequence of 
events is known as a trap. A soft interrupt within MPE means that when I/O completes, the CPU 
will be interrupted . Scheduling information for the process that initiated the I/O will be updated and 
the next time the process runs it will trap to a predetermined interrupt procedure. Intrinsic (system) 
traps are handled by a special procedure designed for that purpose. Normally, if an intrinsic causes 
the trap to be invoked , the system trap handler aborts the user program . You may , however , write a 
procedure into your program to be used instead of the default system trap handler in case of an abort 
error. This method will permit you to recover from such errors in certain cases. For more informa- 
tion on implementing traps, refer to Section V, "OTHER APPLICATIONS OF MPE INTRINSICS" . 

When a program is aborted in a batch job, MPE removes the job from the system unless a : CONTINUE 
command, defined in the MPE V Commands Reference Manual (32033-90006), precedes the com- 
mand which causes the error. If the program is aborted in an interactive session, MPE returns control 
to the terminal. Abort error messages are described in Appendix A, "MPE DIAGNOSTIC 
MESSAGES". 

When an intrinsic is invoked by a process and the DB register is pointing to the DB area in the user's 
stack, a bounds check takes place. This is done to ensure that all parameters in the intrinsic call 
reference addresses lie between the DL and S addresses in the stack (prior to the intrinsic call) . If an 
address outside of these boundaries is referenced , an abort error occurs , or , in the case of file systems 
intrinsics , the condition code is set to CCL and the program continues . 

When an intrinsic is invoked by a process running in Privileged Mode and the DB register points to a 
data segment (i.e. the intrinsic is operating in split-stack mode), the results depend on the particular 
intrinsic. Most intrinsics abort immediately in this case. Others are allowed to execute following a 
bounds check that ensures that all parameters in the intrinsic call reference addresses that lie within 
the data segment . Any boundary violation results in an abort error . Additional special actions taken 
by a particular intrinsic are described in the "Special Considerations" discussion of that intrinsic in 
Section II. 

Figure 1 - 3 illustrates the use of condition code checks in a program . If the condition code is CCE , 
the program displays "MESSAGE TRANSMITTED". For CCL , the message "I/O ERROR OCCURRED" is 
displayed, and the program terminates normally. 
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^CONTROL USLINIT 
<< CONDITION CDDE CHECKS >> 
BEGIN 

ARRAY MESSAGEC0:9):="MESSAGE TO OPERATOR 
ARRAY OKBUFC0:9):="MESSAGE TRANSMITTED "; 
ARRAY ERRBUF(0:9):="I/0 ERROR OCCURRED "; 
INTRINSIC PRINTOP,PRINT; 
PR I NTOP CMESS AGE , 1 , X60 ) \ 
IF = THEN 

PRINTCOKBUF,10,%60); 
GOTO STOP; 
IF < THEN 

PRINTCERRBUF,9,%60); 
STOP: 
END. 



Figure 1 - 3 . Condition Code Checks 



MPE INTRINSICS AND THEIR FUNCTIONS 



MPE intrinsics allow you to access and alter files, request various utility functions, and access and 
manage system resources. When intrinsics are used with certain optional capabilities, it is possible to 
manipulate processes, data segments, and system resources. To help you determine what tasks you 
can accomplish with MPE intrinsics, refer to Table 1-2, which lists each intrinsic, its purpose, and 
the capability needed to use it . 



OPTIONAL CAPABILITIES 



Users with standard MPE capabilities can perform most functions available through the operating sys- 
tem . There are some functions , however , which can only be performed by users with certain optional 
capabilities. These optional capabilities are assigned by the System Manager when creating the user's 
account. The System Manager can alter the capabilities for any account, group, or user on the system 
with the :ALTACCT, :ALTGR0UP, or :ALTUSER command. 

Since many intrinsics require additional capabilities to work, the program which calls them must be 
prepared with these capabilities specified. The creator of the program must have a capability to as- 
sign it to a program. The user need not have a specific capability to run a program, but in order to 
run the program, it must reside in a group with the specific capability. 

The MPE optional capabilities, and what they allow you to do, are explained below. 
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The Process Handling (PH) capability allows you to programmatically : 

• Create and delete processes. 

• Activate and suspend processes. 

• Send "mail" between processes. 

• Change the scheduling of processes . 

• Obtain information about existing processes. 

The Data Segment Management (DS) capability allows you to create and access extra data segments 
from processes during a job or session. 

The Multiple Resource Identification Number (MR) capability allows you to simultaneously lock as 
many global Resource Identification Numbers (RINs) as desired. 

The Privileged Mode (PM) capability allows you to access all areas of the system and use all features 
of the hardware. With this capability you may access all system tables and invoke all system instruc- 
tions, including those in the privileged central processor unit (CPU) instruction set. In short, this 
capability allows you to use the computer on the same terms as the operating system itself . 



CAUTION 



The normal checks and limitations that apply to stan- 
dard users in MPE are bypassed in Privileged Mode . It is 
possible for a Privileged Mode program to destroy file in- 
tegrity, including the MPE operating system software it- 
self. Hewlett-Packard will investigate and attempt to 
resolve problems resulting from the use of Privileged 
Mode code. This service, which is not provided under 
the standard service contract , is available on a time and 
materials billing basis. Hewlett-Packard will not sup- 
port , correct , or attend to any modification of the MPE 
operating system software . 

The User Logging (LG) capability provides a flexible transaction-logging capability which allows you 
to journalize additions and modifications to your data bases and subsystem files. User Logging permits 
you to journalize on either tape or disc. If the data base is lost, the logging tape or disc file can be 
used to recover the lost transactions . 

Programmatic Sessions (PS) capability allows programmatic creation of sessions on any terminal on the 
system (available on G.01 .00 release or later). 
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The Volume Set Usage (UV) or Create Volumes (CV) capabilities allows you to maintain files on 
private disc volumes. If your file group has been structured to use the Private Volumes Subsystem, 
MPE checks to determine if your home volume set is mounted when you create a new disc file with 
the FOPEN intrinsic. Similarly, when you close and save a disc file with the FCLOSE intrinsic, it is 
automatically stored on your home volume set if your account is structured with either of these 
capabilities. (Refer to the MPE V System Operation and Resource Management Reference Manual 
(32033-90005), for more information on Private Volumes.) Optional capabilities are discussed in 
more detail in Section III . 

Table 1-2. Summary of MPE Intrinsics 



INTRINSIC NAME 



ABORTSESS 
ACTIVATE 
ADJUSTUSLF 
ALTDSEG 

ARITRAP 

ASCII 

BEGINLOG 

BINARY 

CALENDAR 

CAUSEBREAK 

CLEANUSL 

CLOCK 

CLOSELOG 

COMMAND 

CREATE 

CREATEPROCESS 



PURPOSE 



Aborts the specified session from the system. 
Activates a process. 
Adjusts directory space in a USL file. 
Alters the size of an extra data segment. 



Enables or disables internal interrupt signals from 
all hardware arithmetic traps. 

Converts a one -word binary number to a numeric 
ASCII string. 

Marks the beginning of a user logging transaction. 



Converts a number from an ASCII string to a binary 
word. 

Returns the calendar date. 

Places a session in BREAK mode. 

Deletes inactive entries from a USL file. 

Returns the actual time according to system timer. 

Closes access to the user logging facility. 

Executes an MPE command programmatically. 

Creates a process. 

Creates a process and can assign $STDIN and 
$STDLIST to any file. 



CAPABILITY REQUIRED 



Standard 

Process Handling (PH) 

Standard 

Data Segment 
Management (DS) 

Standard 
Standard 



User Logging (LG) and 
System Supervisor (OP) 

Standard 



Standard 

Standard 

Standard 

Standard 

User Logging (LG) and 
System Supervisor (OP) 

Standard 

Process Handling (PH) 

Process Handling (PH) 
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Table 1-2. Summary of MPE Intrinsics (Continued) 



INTRINSIC NAME 



CTRANSLATE 

DASCII 

DATELINE 
DBINARY 

DEBUG 
DLSIZE 
DMOVIN 

DMOVOUT 

ENDLOG 

EXPANDUSLF 
FATHER 

FCARD 

FCHECK 

FCLOSE 

FCONTROL 

FDELETE 

FDEVICECONTROL 

FERRMSG 

FFILEINFO 
FGETINFO 



PURPOSE 



Converts a string of characters between EBCDIC 
and ASCII or between EBCDIK and JIS (KANA8). 

Converts a double -word (32 -bit) binary number to 
an ASCII string. 

Returns the current date and time. 

Converts a number from an ASCII string to a 
double -word binary value. 

Invokes the DEBUG facility. 

Expands or contracts the area between DL and DB. 

Copies data from an extra data segment into the 
stack. 

Copies data from the stack to an extra data seg- 
ment. 

Marks the end of a user logging transaction. 

Changes length of a USL file. 

Requests the Process Identification Number (PIN) of 
father process. 

Drives the HP 7 260A Optical Mark Reader. 

Requests details about file input/output errors. 

Closes a file. 

Performs control operations on a file or device. 

Deactivates a Relative I/O (RIO) record. 

Provides control operations to a printer or a 
spooled devicefile. 

Returns message corresponding to FCHECK error 
message. 

Provides access to file information. 

Requests access and status information about a 
file. 



CAPABILITY REQUIRED 



Standard 

Standard 

Standard 
Standard 

Standard 

Standard 

Data Segment 
Management (DS) 

Data Segment 
Management (DS) 

User Logging (LG) and 
System Supervisor (OP) 

Standard 

Process Handling (PH) 

Standard 
Standard 
Standard 
Standard 
Standard 
Standard 

Standard 

Standard 
Standard 
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INTRINSIC NAME 



FINDJCW 
FINTEXIT 
FINTSTATE 

FLABELINFO 
FLOCK 

FLUSHLOG 

FMTCALENDAR 

FMTCLOCK 

FMTDATE 

FOPEN 

FPARSE 

FPOINT 

FREAD 

FREADBACKWARD 

FREADDIR 

FREADLABEL 
FREADSEEK 

FREEDSEG 

FREELOCRIN 

FRELATE 

FRENAME 



PURPOSE 



CAPABILITY REQUIRED 



Searches Job Control Word Table for named JCW. 

Causes return from user's interrupt procedure. 

Enables/disables the software interrupt facility for 
a calling process. 

Returns information from the file label of a disc file. 

Dynamically locks a file. 

(If locking more than one file.) 

Flushes contents of user logging memory buffer to 
logging file. 

Formats specified calendar date. 

Formats specified time of day. 

Formats specified calendar date and time of day. 

Opens a file. 

Parses/validates file designators. 

Sets the logical record pointer for a disc file. 

Reads logical record from file to user's stack. 

Reads logical record backward from current record 
pointer. Data is presented as if read forward. 

Reads a specific logical record from a direct access 
file to the user's data stack. 

Reads a user file label. 

Moves a record from a disc file to a buffer in an- 
ticipation of a FREADDIR intrinsic call. 

Releases an extra data segment. 



Frees all local Resource Identification Numbers 
(RINs) from allocation to a job. 

Determines if file pair is interactive, duplicative, or 
both. 

Renames a disc file. 



Standard 
Standard 
Standard 

Standard 

Standard 
(Multiple RIN (MR)) 

User Logging (LG) and 
System Supervisor (OP) 

Standard 

Standard 

Standard 

Standard 

Standard 

Standard 

Standard 

Standard 

Standard 

Standard 
Standard 



Data Segment 
Management (DS) 

Standard 



Standard 



Standard 
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Table 1-2. Summary of MPE Intrinsics (Continued) 



INTRINSIC NAME 



FSETMODE 
FSPACE 

FUNLOCK 
FUPDATE 
FWRITE 

FWRITEDIR 

FWRITELABEL 
GENMESSAGE 
GETDSEG 

GETINFO 

GETJCW 

GETLOCRIN 

GETORIGIN 

GETPRIORITY 

GETPRIVMODE 

GETPROCID 

GETPROCINFO 

GETUSERMODE 

INITUSLF 

IODONTWAIT 

IOWAIT 

JOBINFO 



PURPOSE 



Activates or deactivates file access modes. 

Moves a physical record pointer forward or 
backward on a tape or disc file. 

Dynamically unlocks a file. 

Updates (writes) a logical record in a disc file. 

Writes a logical or physical record or portion of a 
record from user's stack to a file on any device. 

Writes a specific logical record from the user's 
stack to a disc file. 

Writes a user file label. 

Accesses the MPE message system. 

Creates an extra data segment. 

Gets inf o/parm values from :RUN command or 
CREATEPROCESS intrinsic. 

Returns the value of the system -defined Job 
Control Word, JCW. 

Acquires local RINs. 

Determines source of activation call for process. 

Changes the priority of a process. 

Dynamically enters Privileged Mode. 

Requests PIN of a son process. 

Requests status data on a father or son process. 

Dynamically returns to non -Privileged Mode. 

Initializes a USL file to the empty state. 

Initiates completion operations for an I/O request. 

Initiates completion operations for an I/O request. 

Returns job/session related information. 



CAPABILITY REQUIRED 



Standard 
Standard 

Standard 
Standard 
Standard 

Standard 

Standard 

Standard 

Data Segment 
Management (DS) 

Standard 

Standard 

Standard 

Process Handling (PH) 
Process Handling (PH) 
Privileged Mode (PM) 
Process Handling (PH) 
Process Handling (PH) 
Privileged Mode (PM) 
Standard 

Privileged Mode (PM) 
Privileged Mode (PM) 
Standard 
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INTRINSIC NAME 



PURPOSE 



CAPABILITY REQUIRED 



KILL 

LOADPROC 

LOCKGLORIN 

LOCKLOCRIN 

LOCRINOWNER 

LOGINFO 

LOGSTATUS 

MAIL 
MYCOMMAND 

OPENLOG 

PAUSE 

PRINT 

PRINTFILEINFO 

PRINTOP 
PRINTOPREPLY 

PROCINFO 
PROCTIME 
PTAPE 

PUTJCW 
QUIT 

QUITPROG 
READ 



Deletes a son process. 

Dynamically loads a library procedure. 

Locks a global RIN. 

Locks a local RIN. 

Determines PIN of a process locking a local RIN. 

Obtains information from user logging buffer. 



Provides information about an opened user logging 
file. 

Tests mailbox status. 

Parses (delineates and defines parameters for 
user -supplied command image. 

Provides access to the user logging facility. 



Suspends process for a specific number of seconds 

Prints character string on job/session list device. 

Prints a file information display on a job/session list 
device. 

Prints a character string on the System Console. 

Prints a character string on the System Console 
and solicits a reply. 

Provides access to process information. 

Returns the accumulated CPU time for a process. 

Copies input from paper tapes which do not contain 
X-OFF control characters to a disc file. 

Assigns the value of a particular JCW in JCW Table. 

Aborts a process. 

Aborts the entire user process structure. 

Reads an ASCII string from $STDIN into an array. 



Process Handling (PH) 

Standard 

Standard 

Standard 

Standard 

User Logging (LG) and 
System Supervisor (OP) 

User Logging (LG) and 
System Supervisor (OP) 

Process Handling (PH) 

Standard 

User Logging (LG) and 
System Supervisor (OP) 

Standard 

Standard 

Standard 

Standard 
Standard 

Standard 
Standard 
Standard 

Standard 
Standard 
Standard 
Standard 
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Table 1-2. Summary of MPE Intrinsics (Continued) 



INTRINSIC NAME 


PURPOSE 


CAPABILITY REQUIRED 


READX 


Reads an ASCII string from $STDINX into an array. 


Standard 


RECEIVEMAIL 


Receives mail from another process. 


Process Handling (PH) 


RESETCONTROL 


Resets terminal to accept CONTROL -Y signal. 


Standard 


RESETDUMP 


Disables the abort stack analysis facility. 


Standard 


SEARCH 


Searches an array for a specified entry or name. 


Standard 


SENDMAIL 


Sends mail to another process. 


Process Handling (PH) 


SETDUMP 


Enables the stack analysis facility. 


Standard 


SETJCW 


Sets bits in the system Job Control Word, JCW. 


Standard 


STACKDUMP 


Dumps selected parts of stack to file. 


Standard 


STARTSESS 


Initiates a session on the specified terminal. 


Programmatic Sessions 
(PS) 


SUSPEND 


Suspends a process. 


Process Handling (PH) 


SWITCHDB 


Switches DB register pointer. 


Privileged Mode (PM) 


TERMINATE 


Terminates a process. 


Standard 


TIMER 


Returns system timer information. 


Standard 


UNLOADPROC 


Dynamically unloads a library procedure. 


Standard 


UNLOCKGLORIN 


Unlocks a global RIN. 


Standard 


UNLOCKLOCRIN 


Unlocks a local RIN. 


Standard 


WHO 


Returns information about a user. 


Standard 


WRITELOG 


Writes a record to a logging file. 


User Logging (LG) and 
System Supervisor (OP) 


XARITRAP 


Enables or disables the user -written software 
arithmetic trap. 


Standard 


XCONTRAP 


Enables or disables the CONTROL -Y trap. 


Standard 


XLIBTRAP 


Enables or disables the software library trap. 


Standard 


XSYSTRAP 


Enables or disables the system trap. 


Standard 


ZSIZE 


Alters current Z to DB area. 


Standard 1 
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This section contains descriptions of all MPE intrinsics, arranged alphabetically. Each intrinsic de- 
scription provides the intrinsic name, describes the call, defines parameters, explains condition codes, 
and where applicable gives information on the functional return , special considerations , and areas of 
additional discussion . 



INTRINSIC NAME 



Following the intrinsic name, you will find its assigned number and a brief summary of its function. 
The intrinsic number is useful in determining error diagnosis and for implementing trap procedures. 
Several intrinsics may have the same number (e.g. BEGINLOG, ENDLOG, and WRITELQG) since they are 
really the same procedure with alternate entry points. Other intrinsics have no number at all, be- 
cause they will not abort and therefore do not need an intrinsic number for error diagnosis. 



SYNTAX 



The syntax area contains the complete intrinsic call description, enclosed in a box. The intrinsic call 
descriptions are in the format shown below : 



0-V IV LV 

ACTIVATE Cpin, susp ); 



Required parameters, such as pin, are shown in bold italics. Optional parameters, such as susp, 
are shown in standard italics. The mnemonics which appear over the parameters indicate their 
type, and whether it must be passed by reference (the default), or by value. (Refer to Section I for a 
discussion of passing parameters by reference and by value.) For example IV, which appears over 
pin, indicates that the parameter is an integer variable which must be passed by value. The 
mnemonics have the following meanings : 



BA 


Byte array 


IV 


Integer by value 


BP 


Byte pointer 


L 


Logical by reference 


D 


Double by reference 


LA 


Logical array 


DA 


Double array 


LV 


Logical by value 


DV 


Double by value 


0-P 


Option privileged 


I 


Integer by reference 


0-V 


Option variable 


IA 


Integer array 


R 


Real 



In addition to the mnemonics shown over the parameters, the mnemonic 0-V is shown for some intrin- 
sics to denote "option variable". Option variable means that the intrinsic contains optional 
parameters and a complete call to this intrinsic need only specify the optional parameters desired by 
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the programmer. Additionally, 0-P is shown for those intrinsics (i.e. GETPRIVMODE) which can only 
be called when running in Privileged Mode. The ACTIVATE intrinsic, for example, contains two 
parameters: pin, which is a required integer that must be passed by value; and susp, an optional 
logical that, if included in the intrinsic call, must be passed by value. Additionally, the intrinsic is 
option variable, which restates that some parameters (susp in this instance) are optional. 



NOTE 



If a byte array is passed to a parameter which requires a 
logical array, SPL will convert it to a logical array by 
shifting one bit to the right. Because of addressing 
modes inherent in the HP 3000 architecture, this shift 
can cause the wrong half bank of memory to be ad- 
dressed, possibly resulting in the process aborting with a 
bounds violation. SPL will print a warning message 
when this condition occurs. This condition can be 
avoided by setting a byte array equivalent to a logical 
array for the message parameter. 



FUNCTIONAL RETURN 



Certain intrinsics return a value to the calling program ("type procedures"). A type procedure 
returns the value of a specified type (e.g. integer, real) in place of its name. (The result is actually 
returned to the top of stack and thus can be used in the rest of the expression). If the intrinsic is not 
a type procedure, this portion of the intrinsic description is omitted. The symbol " : =" is the SPL as- 
signment identifier which means "is assigned the value of" or "receives the value of". This conven- 
tion is used throughout this section for consistency. It should not be interpreted that the value would 
be unavailable in languages other than SPL. The intrinsic call description format for type procedure 
intrinsics is illustrated below with the READ intrinsic : 



I LA IV 

length : =RERD(.message , expected! ) ; 



The READ intrinsic returns the positive length of the input actually read to an integer variable. The 
type, (e.g. integer, double), is signified by a mnemonic above the descriptive word. Thus, the READ 
intrinsic is in effect an integer procedure , message is a required logical array , and expectedl is a 
required integer parameter which must be passed by value . 

A program using an intrinsic that returns a value may choose to omit the assignment (that is, the 
return variable is not required). The compiler will generate code to cause the return value to be 
deleted if a variable is not specified. Thus, the following examples are both legal calls of the READ 
intrinsic : 

LEN:=READCMESS,20); ** User program may access LEN ** 

READ(MESS,20) ** Return variable unavailable ** 
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PARAMETERS 

All parameters are described. In the intrinsic call description, required parameters are shown in bold 
italics, and optional parameters are shown in large (12-point) standard italics. Within the 
text of this manual, this distinction is not shown for required and optional parameters, and all para- 
meters are shown in small (1 0-point) standard italics. 

For some parameters certain bit settings have particular meanings; when significant these bit settings 
and their meanings will be noted. In other instances, (e.g. with logical parameters), many different 
values will have the same result (i.e. setting bit (15:1)=1 has the same interpretation as entering 
TRUE). For more information on the various options for a given parameter type refer to the Systems 
Programming Language Reference Manual (30000-90024). 

Bit groups are denoted using the standard SPL notation. Thus bit (15:1) indicates bit 15; bits (0:3) 
indicates bits 0,1, and 2. Bit 1 5 is on the right and is the least significant bit. 

CONDITION CODES 

Condition codes are included for each intrinsic. (Refer to "Intrinsic Call Errors" in Section I for a 
detailed description of the meaning and use of condition codes.) 

SPECIAL CONSIDERATIONS 

The special considerations portion of the description is omitted unless the intrinsic requires some spe- 
cial circumstances for proper execution. Therefore, unless explicitly stated the intrinsic does not: 

• Operate in split -stack mode. 

• Require special capabilities. 

• Require a privileged call. 

Required Capability 

When you run a program file , the file system checks your group capabilities to see if you can access 
the file. Also, the capability of the program file (established at PREParation time) is checked against 
the capability of the group in which the file resides. If the capability of the file does not exceed the 
capability of the group, the program executes. Additional capability checking, however, is done if 
the program calls an intrinsic. Some intrinsics require that the program file and the user have suffi- 
cient capability to call them. If an intrinsic requires a special capability, it will be noted in the dis- 
cussion of that intrinsic. Optional capabilities are discussed in Sections I and III. 
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Intrinsic Descriptions 

Split-Stack Operations 

During normal operation, DB (the Data Base register) points to the user's process stack. Some opera- 
tions with extra data segments require that DB be set to the base of the extra data segment, while DL 
(the Data Limit register) and all other data registers (Z, the stack limit register; Q, the stack marker 
register; and S, the top of stack register) remain associated with the stack. When a process is operat- 
ing in this mode it is said to have a split -stack. When accessing some parts of the operating system 
which use extra data segments, you are considered to be operating in split-stack mode, implicitly. It 
is also possible, if you are a privileged user, to force your process to operate in split -stack mode ex- 
plicitly by calling the SN I TCHDB intrinsic. 

You should be aware, however, that it is possible for a privileged user to inadvertently destroy the 
operating system when operating in split -stack mode. Operating safely in split -stack mode requires 
extensive knowledge of the compiler: specifically, how the compiler assigns storage. For example, 
during normal operation, DB-relative variables point to the user's stack, but to different locations 
during split-stack mode operation. Thus, it is possible to unintentionally change data in areas which 
are normally reserved for MPE. Refer to the System Programming Language Textbook 
(30000-90025) for more information on the process stack. 

When a process is operating in split -stack mode, whether implicitly or explicitly, you must recognize 
that some of the intrinsics you can normally call may not be called when DB does not point to the 
stack. Such intrinsics, if called by a privileged process while the DB register is not set to the user's 
stack, can result in a system failure. If you are a normal user, (not operating in Privileged Mode), 
you need not concern yourself with this restriction, and you can assume that unless it is stated other- 
wise, an intrinsic will not operate in split-stack mode. However, if you have Privileged Mode 
capability, exercise extreme caution when calling intrinsics which operate in split-stack mode. 



CAUTION 



The normal checks and limitations that apply to users 
with standard (default) capabilities are bypassed in 
Privileged Mode. It is possible for a Privileged Mode 
program to destroy file integrity, including the MPE 
operating system software itself. Hewlett-Packard will, 
upon request, investigate and attempt to resolve 
problems resulting from the use of Privileged Mode 
code. This service, which is not provided under the 
standard Service Contract, is available on a time and 
materials billing basis. Hewlett-Packard will not sup- 
port, correct, or attend to any modification of the MPE 
operating system software. 



ADDITIONAL DISCUSSION 

Where applicable, the "Additional Discussion" section will reference parts of this or other 
Hewlett-Packard manuals for additional information on the use of a particular intrinsic. 
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ABORTSESS 

INTRINSIC NUMBER 196 



Aborts the specified session from the system. (Available only on version G.01 .00 and later.) 

SYNTAX 



IV DV IA 

ABORTSESS (jsid, jsnum, er*rorsto* ) ; 



ABORTSESS provides programmatic access to the functions of the : ABORT JOB command. The caller of 
ABORTSESS must have : ABORT JOB rights to the specified session. : ABORT JOB rights can be dis- 
tributed with the : ALLOW command, or the : JOBSECURITYcan be set low. 



PARAMETERS 

jsid 



jsnum 
exvporstat 



integer by value (required) 

Indicates the type of Command Interpreter (CI) process. If an earlier 
STARTSESS call was successful , the value returned is 1 ; if unsuccessful , the 
value is 0. When the value returned to jsid is 1 , jsid and jsnum can be 
used as input to JOB INFO to check, on the attributes of the session. 

double by value (required) 

A 3 2 -bit value which, when used with jsid, uniquely identifies the session. 

integer array (required) 

A two -element array in which the status of the call is returned. The second 
element is reserved for future use, and will always contain a zero. The 
first element will contain a zero if no errors occurred. If an error occurs 
one of the following error values is returned in the first element : 

Error No. Meaning 

1 Job security too high, or job is not yours. 

2 Job does not exist. 

3 Job is being introduced and cannot be aborted when in the 
INTRO state. 



CONDITION CODES 



The condition code remains unchanged . 



SPECIAL CONSIDERATIONS 



ABORTSESS requires the caller to be allowed : ABORT JOB via the : ALLON command , have Account 
Manager (AM) or System Manager (SM) capabilities, or that the : JOBSECURITY be set low. 
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ADDITIONAL DISCUSSION 

MPE V Commands Manual (32033-90006). 
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ACTIVATE 

INTRINSIC NUMBER 104 



Activates a process . 

SYNTAX 



0-V IV LV 

ACTIVATECp£n,susp); 



After a process has been created, it must be activated in order to run. Once activated, the process 
runs until it is suspended or deleted. A newly created process can only be activated by its father. A 
process that has been suspended (with the SUSPEND intrinsic) can be reactivated by its father, or any 
of its sons, as specified in the susp parameter of the ACTIVATE and SUSPEND intrinsics. 

The operating system guarantees that there will be no process switching (to some other process) be- 
tween activation of the called process and suspension of the calling process . 

The ACTIVATE intrinsic aborts the calling process (and possibly the entire job/session) if: 

1. The group in which the program file resides does not have Process Handling (PH) capability, or 
the program was not prepared with Process Handling capability. 

2. The required parameter pin is omitted. 

3. A request to activate the father would result in activation of a job or session main process or a 
system process. 



PARAMETERS 

pin 



susp 



integer by value (required) 

Process Identification Number (PIN). An integer specifying the PIN for 
the son or father process to be activated. The PIN number to activate a 
father process is always zero. The called process must always be expecting 
an activation from the caller as noted in the discussion of the SUSPEND and 
CREATE intrinsics. 

logical by value (optional) 

A word that specifies one of the following : 

• The calling process is to be suspended while the called process is ac- 
tivated and commences execution. 

• The called process is to be activated by the operating system but will 
not commence execution immediately. Instead, control is returned to 
the calling process which will continue execution. 

When susp is omitted or is zero , the calling process remains active . When 
susp is specified (and not zero), the calling process is suspended. The bits 
(14:2) of susp specify the anticipated source of the call that later will 
reactivate the calling process. 
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Bit (15:1) Father activation bit . 

=0 The process does not expect to be activated by its father. 

= 1 The process expects to be activated by its father . 

Bit (14:1) Son activation bit . 

=0 The process does not expect to be activated by one of its sons. 

= 1 The process expects to be activated by one of its sons. 

If both bits=l , the suspended process can be activated by either its father or 
one of its sons. 

Bits (0:14) Reserved for MPE and should be set to zero. 

Default : Calling process remains active . 

CONDITION CODES 

CCE Request granted. Called process is activated. The calling process is 

suspended if susp was specified . 

CCG The called process is already active. The calling process is suspended if susp 

was specified . 

CCL Request denied because the called process was not expecting activation by 

this calling process , an illegal pin parameter was specified , or the susp pa - 
rameter was specified improperly. 

SPECIAL CONSIDERATIONS 

Split -stack calls permitted. 

Process Handling (PH) capability required. 

ADDITIONAL DISCUSSION 

"Creating an Extra Data Segment" and "Creating and Activating Processes" in Section III. 
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ADJUSTUSLF 

INTRINSIC NUMBER 83 



Adjusts directory space in a USL file . 

SYNTAX 



I IV IV 

errnum : = ADJUSTUSLF Quslf man, records ) ; 



The ADJUSTUSLF intrinsic moves the start of the information block, forward or backward on a User 
Subprogram Library (USL) file, thereby increasing or decreasing, respectively, the space available for 
the file directory block. This does not change the overall length of the file. This intrinsic is intended 
for programmers writing compilers. Refer to the MPE Segmenter Reference Manual (30000-9001 1) 
for a discussion of USLs , the ADJUSTUSLF intrinsic , information blocks , and directory blocks . 

FUNCTIONAL RETURN 

errnum integer 

Returns an error number if an error occurs. If no error occurs, no value is 
returned . The error number returned corresponds to the following errors : 

Error No . Meaning 

The file specified by uslfnum was empty, an unexpected 
end -of -file was encountered when reading the uslfnum, 
or an unexpected end -of -file was encountered when writ- 
ing on the uslfnum. 

1 Unexpected input/output error occurred . 

4 Your request attempted to exceed the maximum file 

directory size (32,768 words). 

5 Insufficient directory space. 

6 Insufficient space was available in the USL file informa- 
tion block. 
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PARAMETERS 

ustfman integer by value (required) 

A word supplying the file number of the USL file (as returned by FOPEN) . 

records integer by value (required) 

A word supplying the signed record count. If records is greater than zero, 
the information block is moved toward the end -of -file in the USL file, in- 
creasing the space available for the directory block and decreasing the space 
available for the information block. If records is less than zero, the infor- 
mation block is moved toward the start of the USL file, decreasing the 
directory block space and increasing the information block space . 

CONDITION CODES 

CCE Request granted . 

CCG Not returned by this intrinsic. 

CCL Request denied . An error number was returned to errornum indicating the 

reason for this failure. 

ADDITIONAL DISCUSSION 

MPE Segmenter Reference Manual (30000-9001 1). 
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ALTDSEG 

INTRINSIC NUMBER 134 



Alters the size of an extra data segment. 

SYNTAX 



LV IV I 
ALTDSEGCindex,inc,size) j 



The ALTDSEG intrinsic alters the current size of an extra data segment. ALTDSEG can be used to 
reduce the storage required by the segment when it is moved into main memory, then used again to 
expand storage as required, thus allowing more efficient use of memory. 

Expansion and contraction is accomplished in even multiples of four words, which are rounded up. 
For example : 



Present Segment 


Change Value (inc) 


New Segment 


Size (Words) 


(Words) 


Size (Words) 


128 


-3 


128 


128 


-4 


124 


128 


+ 1 


132 


128 


+3 


132 


128 


+4 


132 



When a data segment is created through GETDSEG sufficient virtual space is allocated by the system to 
accommodate the original length of the data segment. This virtual space is allocated in increments of 
pages, where the number of words per page is set when the system is configured (typically 512 
words/page). For example, creation of a data segment with a length of 600 words would result in 
two virtual pages being allocated for the data segment (space for 1024 words). 

In no case may ALTDSEG increase the size of a data segment to exceed the virtual space originally allo- 
cated through GETDSEG. On version G.00.00 and later when GETDSEG is called in non -Privileged 
Mode, the ALTDSEG intrinsic must also be called in non -Privileged Mode. When GETDSEG is called in 
Privileged Mode, the ALTDSEG intrinsic must be called in Privileged Mode. 

PARAMETERS 

index logical by value (required) 

A word containing the logical index of the extra data segment, obtained 
from the GETDSEG call. 

inc integer by value (required) 

The value, in words, by which the data segment is to be changed. A posi- 
tive integer value requests an increase, and a negative integer value 
requests a decrease. 
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size integer (required} 

A word to which the new size of the data segment is returned after in- 
crementing or decrementing occurs. 



CONDITION CODES 

CCE Request granted. 

CCG Request not fully granted. An illegal decrement requesting a new total 

segment size of zero or less, or an illegal increment requesting a new size 
greater than the virtual space originally assigned by GETDSEG, was at- 
tempted. In the first case, the current size remains in effect. In the 
second case , the size of the virtual space is granted and this size is returned 
through the size parameter. 

CCL Request denied because an illegal index parameter was specified. 

SPECIAL CONSIDERATIONS 

Data Segment Management (DS) capability required. 

ADDITIONAL DISCUSSION 

"Changing the Size of an Extra Data Segment" in Section III. 
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ARITRAP 

INTRINSIC NUMBER 51 



Enables or disables internal interrupt signals from all hardware arithmetic traps. 

SYNTAX 



LV 
ARITRAP Cstote); 



When a user process begins execution, all internal arithmetic user traps are enabled. That is, if an 
arithmetic error occurs in the user process, it is aborted in the trap mechanism. The possible inter- 
rupts listed below are collectively called the arithmetic user traps : 



Integer Overflow. 
Floating Point Overflow. 
Floating Point Underflow. 
Integer Divide By Zero. 
Floating Point Divide By Zero. 
Double Precision Overflow. 
Double Precision Underflow. 



Double Precision Divide By Zero. 
Decimal Overflow. 
Invalid ASCII Digit. 
Invalid Decimal Digit . 
Invalid Source Word Count . 
Invalid Decimal Operand Length. 
Decimal Divide By Zero. 



The traps may be collectively enabled/disabled with the ARITRAP intrinsic call. 

The ARITRAP intrinsic always clears the overflow indicator (bit (4:1)) located in the caller's status 
word. 



PARAMETERS 

state 



logical by value (required) 

A word in which bit (15:1) specifies whether arithmetic traps are enabled 

or disabled. The settings for bit (15:1) are as follows: 

=0 Arithmetic traps are disabled. 

= 1 Arithmetic traps are enabled . 

Bits (0:15) are reserved for MPE and should be set to zero. 



CONDITION CODES 

CCE Request granted. The arithmetic traps were originally disabled. 

CCG Request granted. The arithmetic traps were originally enabled . 

CCL Not returned by this intrinsic. 

ADDITIONAL DISCUSSION 

"Enabling and Disabling Traps" in Section V. 
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ASCII 

INTRINSIC NUMBER 63 
Converts a one -word binary number to a numeric ASCII string. 

SYNTAX 



I LV IV BA 

numchar : =ASC 1 1 (word, base, string) ; 



Any 16-bit binary number can be converted to a different base and represented as a numeric charac- 
ter ASCII string by using the ASC 1 1 intrinsic call. 



FUNCTIONAL RETURN 



numchar 



integer 

The number of characters in the resulting string. 



PARAMETERS 

word 
base 



string 



logical by value (required) 

The number to be converted to an ASCII string. 

integer by value (required) 

One of the following integers indicating octal or decimal conversion : 

8 Octal conversion (pads with zeros). 

1 Decimal conversion (left -justified ) . 

- 1 Decimal conversion (right -justified ) . 

If any other number is entered in this parameter, the intrinsic causes the 
user process to abort . 

byte array (required) 

A byte array into which the converted value of word is placed . This array 
must be long enough to contain the result. No result, however, will exceed 
six characters. For octal conversion (base = 8), six characters, including 
leading zeros, are always returned in string. In octal conversions, the 
length returned by ASCII is the number of significant (right- justified) 
characters in string (excluding leading zeros). If word = 0, the length 
(numchar) returned by ASCI I is 1 . 

For decimal conversions, word is considered as a 16 bit, two's complement 
integer ranging from -32768 to +32767. If the value of word = 0, only 
one zero character is returned in string. The length (numchar) returned by 
ASCI I is the total number of characters in string (including the sign). If 
word = 0, the length returned by ASCI I is 1 . 
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For decimal left- justified conversions {base =10), leading zeros are removed 
and the numeric ASCII result is left -justified in string. Thus, the most 
significant digit (or the "-" sign) is in string{0), the next most significant 
digit is in string( 1 ) , and so on. 

For decimal right -justified conversions {base ■ -10), the result is right- 
justified in string. Thus, the least significant digit is in string{0), the next 
least significant digit is in string (-1), and so on. 

For right- justified conversions, the byte array into which the converted 
value is to be placed must specify the right-most byte into which data is to 
go. For example, if string is a 10- byte array declared as: 

BYTE ARRAY STRINGC0:9); 

Then it must be specified in the ASC 1 1 intrinsic call as follows (for right 
justification) : 

NUMCHAR:=ASCIICWORD,-10,STRING(9)>; 

The result will be right -justified in string, with the right -most digit of the 
result contained in the last (right -most) byte of string. 



CONDITION CODES 

The condition code remains unchanged. 

ADDITIONAL DISCUSSION 

"Converting Numbers from Binary Code to ASCII Strings" in Section V. 
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BEGINLOG 

NO INTRINSIC NUMBER ASSIGNED 
Marks the beginning of a user logging transaction . 

SYNTAX 



D LA I I I 

BEG I NLDG (.index ,data , len ,mode , status ) ; 



The BEGINLOG intrinsic posts a special record to the user logging file to mark the beginning of a logi- 
cal transaction. When BEG I NLDG is used, the logging memory buffer is flushed to ensure that the 
record gets to the logging file. BEGINLOG can also be used to post data to the logging file by using the 
data parameter. This use of BEGINLOG performs the same function as the WRITELOG intrinsic. 



PARAMETERS 

index 

data 



len 



mode 



status 



double (required) 

The parameter returned from OPENLOG that identifies the user's access to 

the logging system. 

logical array (required) 

An array in which the actual information to be logged is passed. A log 
record contains 128 words of which 119 words are available to the user. 
Thus, the most efficient use of logging file space is to structure arrays with 
lengths in multiples of 1 19 words. 

integer (required) 

The length of the data in data. A positive integer indicates words, and a 
negative integer indicates bytes. If the length is greater than 1 19 words (or 
238 bytes), the information in data will be divided into two or more physi- 
cal log records. 

integer (required) 

An integer which specifies whether you want your process impeded by the 
logging process if the logging buffer is full. If it is not possible to log the 
transaction and the mode is set to NO WAIT, the BEGINLOG intrinsic will 
return an indication via status that the request was not completed. The 
following integers are valid for this parameter : 

Specifies WAIT. 

1 Specifies NO WAIT. 

integer (required) 

One of the following integers that the logging system uses to return infor- 
mation on the status of the intrinsic call to the user: 
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Message No . 



1 

2 
3 

4 
5 
6 

7 

8 

9 

10 

12 

13 

14 

15 

16 



Meaning 

No error occurred for this call. 

User requested NOW AIT mode and the logging process is 
busy. 

Parameter out of bounds in logging intrinsic . 

Request to open or write to a logging process that is not 
running. 

Incorrect index parameter passed to a logging intrinsic. 

Incorrect mode parameter passed to a logging intrinsic. 

User request denied because logging process is suspended . 

Illegal capability. Must have User Logging (LG) and 
System Supervisor (OP) capabilities to use a logging 
intrinsic . 

Incorrect password passed to a logging intrinsic . 

Error occurred while writing to the logging file. 

Invalid DST passed to logging system intrinsic. 

System is out of disc space, logging cannot proceed. 

No more logging entries. 

Invalid access to logging file. 

End -of -file on user logging file. 

Invalid logging identifier. 



CONDITION CODES 

The condition code remains unchanged. 

SPECIAL CONSIDERATIONS 

User Logging (LG) and System Supervisor (OP) capabilities required. 

ADDITIONAL DISCUSSION 

"User Logging" in Section III. 
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BINARY 

INTRINSIC NUMBER 62 
Converts a number from an ASCII string to a binary word. 

SYNTAX 



I BA IV 

bineqo : =BI NARY (.string , length ) ; 



FUNCTIONAL RETURN 

bineqo integer 

The binary equivalent of the numeric string. 

PARAMETERS 

string byte array (required) 

Contains the octal or signed -decimal number (ASCII characters) to be con- 
verted. If the character string in this array begins with a percent sign (%), 
it is treated as an octal value. The string is treated as a decimal value if it 
begins with a plus sign, a minus sign or a number. Leading blanks are not 
allowed, and are treated as illegal characters. 

length integer by value (required) 

An integer representing the length (number of bytes) in the byte array con- 
taining the ASCII -coded value. If the value of length is 0, the intrinsic 
returns to the calling process. When the value of length is negative, the 
intrinsic causes the user process to abort . 

CONDITION CODES 

CCE Successful conversion. A one -word binary value is returned to the user's 

process . 

CCG A word overflow, possibly resulting from too many characters {string 

number too large), occurred in the word (bineqv) returned. 

CCL An illegal character was encountered in the byte array specified by string. 

For example, the digits 8 or 9 were specified in an octal value. 

ADDITIONAL DISCUSSION 

"Converting Numbers from an ASCII Numeric String to a Binary Coded Value" in Section V. 
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CALENDAR 

INTRINSIC NUMBER 43 



Returns the calendar date. 

SYNTAX 



L 
date :=CALENDAR; 



FUNCTIONAL RETURN 

date logical 

The calendar date is returned in the format : 

Bits (7:9) - The day of the year. 

Bits (0:7) - The year of the century. 

CONDITION CODES 

The condition code remains unchanged. 

SPECIAL CONSIDERATIONS 

Split-stack calls permitted. 

ADDITIONAL DISCUSSION 

"Obtaining the Calendar Date" in Section V. 
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CAUSEBREAK 

INTRINSIC NUMBER 56 
Places a session in BREAK mode. 

SYNTAX 



CAUSEBREAK; 



Using the CAUSEBREAK intrinsic will interrupt an interactive session. While not applicable in jobs, 
the CAUSEBREAK intrinsic is the programmatic equivalent to pressing [break] in a session. Execution 
of the process can be resumed where the interruption occurred by entering the command : 

: RESUME 

CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied because the intrinsic was not called from an interactive 

session. 

SPECIAL CONSIDERATIONS 

Split -stack calls permitted. 

ADDITIONAL DISCUSSION 

"Requesting a Process Break" in Section V. 



2-20 



Deletes inactive entries from a USL file. 

SYNTAX 



CLEANUSL 

NO INTRINSIC NUMBER ASSIGNED 



I IV BA 

filenum: =CLEANUSL(wsZ/ man, filename) ; 



CLEANUSL deletes all inactive entries from currently managed USL files and returns the file number 
of the new USL file. The condition code, therefore, must be tested immediately on return from the 
intrinsic. Unpredictable results occur if an error number is used as a file number. 



FUNCTIONAL RETURN 



filenum 



integer 

The new file number. If an error occurs, filenum is one of the following 

error numbers : 



Error No. 


1 

7 
12 



Meaning 

Unexpected end -of -file (EOF) marker on either the old 
or the new USL file . 

Unexpected I/O error on either the old or the new USL 
file. 

Unable to open new USL file. 

Invalid USL file. 



PARAMETERS 

uslfnum 



filename 



integer by value (required) 

A word supplying the file number of the file. 

byte array (required) 

The name to be given to the cleaned file. The array must end with a 
blank, but it can be all blanks. If the array is all blanks, it deletes the in- 
active entries. 



2-21 



CONDITION CODES 

CCE Request granted. The new file number is returned. 

CCG Not returned by this intrinsic. 

CCL Request denied . An error number is returned to filenum . 

ADDITIONAL DISCUSSION 

MPE Segmenter Reference Manual (30000-9001 1). 
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CLOCK 



INTRINSIC NUMBER 44 



Returns the actual time according to the system timer . 

SYNTAX 



D 

time :=CLDCK; 



FUNCTIONAL RETURN 

time double 

A double-word containing the actual time, as monitored by the system 
timer. The first word contains the hour of the day and the minute of the 
hour ; the second word contains seconds and tenths of seconds as follows : 

Word 1 : 

Bits (8:8) - The minute of the hour. 

Bits (0:8) - The hour of the day. 

Word 2: 

Bits (8:8) - The tenths of seconds. 

Bits (0:8) - The seconds. 

CONDITION CODES 

The condition code remains unchanged . 

SPECIAL CONSIDERATIONS 

Split-stack calls permitted. 

ADDITIONAL DISCUSSION 

"Time and Date Intrinsics" in Section V. 
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CLOSELOG 

INTRINSIC NUMBER 212 



Closes access to the user logging facility . 

SYNTAX 



D I I 

CLOSELOG (index f mode , status ) ; 



Effective with the G.02.00 version of MPE, the number of users and log entries are independent of 
the number of times the OPENLOG/CLOSELOG intrinsics are called within an application. A logging 
buffer entry is obtained and the user count is incremented only if this is the first OPENLOG call for 
this user. A counter is used to keep track of the number of times a user has called OPENLOG and 
CLOSELOG. The counter is incremented for every DPENLOG and decremented for every CLOSELOG. 
This is done to ensure the entry in LOGBUFF is released only if this is the last CLOSELOG call for this 
user (i.e. counter=0). 



PARAMETERS 

index 

mode 



status 



double (required) 

The parameter returned from OPENLOG that identifies your access to the 

logging facility. 

integer (required) 

An integer used to indicate whether your process should be suspended if 
your request for service cannot be completed immediately. The following 
integers are valid for this parameter : 

Specifies WAIT. 

1 Specifies NO WAIT. 

integer (required) 

An integer which indicates one of the following status conditions : 



Message No . 


1 

2 
3 

4 
5 
6 



Meaning 

No error occurred for this call. 

User requested NOW AIT mode and the logging process is 
busy. 

Parameter out of bounds in logging intrinsic. 

Request to open or write to a logging process that is not 
running . 

Incorrect index parameter passed to a logging intrinsic. 

Incorrect mode parameter passed to a logging intrinsic. 

User request denied because logging process is suspended. 
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8 

9 

10 

12 

13 

14 

15 

16 

CONDITION CODES 

The condition code remains unchanged. 

SPECIAL CONSIDERATIONS 

User Logging (LG) and System Supervisor (OP) capabilities required. 

ADDITIONAL DISCUSSION 

"User Logging" in Section HI. 



Illegal capability. Must have User Logging (LG) and 
System Supervisor (OP) capabilities to use a logging 
intrinsic . 

Incorrect password passed to a logging intrinsic. 

Error occurred while writing to the logging file. 

Invalid DST passed to logging system intrinsic. 

System is out of disc space, logging cannot proceed. 

No more logging entries. 

Invalid access to logging file. 

End-of-file on user logging file. 

Invalid logging identifier. 
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COMMAND 

INTRINSIC NUMBER 68 
Executes an MPE command programmatically. 

SYNTAX 



BA II 

C0lWANI)icominnge 3 e]pro]p 3 param') ; 



User -defined commands (UDCs) cannot be used with the COMMAND intrinsic . 



PARAMETERS 



cotatnage 



BTVOV 



param 



byte array (required) 

Contains an ASCII string of not more than 278 characters consisting of a 
command and parameters, terminated by a carriage return. The carriage 
return character (%15) must be the last character of the command string. 
No prompt character, however, should be included in this string. The corn- 
image array will be altered by the COMMAND intrinsic (lowercase characters 
in it will be shifted to uppercase), and will be returned to the caller in 
uppercase . 

integer (required) 

A word to which any error code set by the command is returned. This is 
the same error code that would appear on a job/session list device if the 
command was part of an input stream, i.e. a Command Interpreter rather 
than file system error code. If no error occurs, error returns zero. If an 
MPE warning was detected, a negative number is returned (for example, 
" -383" is returned if CI WARN 383 is detected). 

integer (required) 

A word to which the number (index) of the erroneous parameter is return- 
ed. If no parameters are in error, param returns zero. If there are errors, 
param may be zero or some positive integer. In the case where an error 
refers to a file system problem , param is the file system error code . 



CONDITION CODES 



CCE 



CCG 



CCL 



Request granted although a Command Interpreter warning may have been 
detected. 

An executor -dependent error, such as an erroneous parameter, prevented 
execution of the command. The numeric error code is contained in error. 
The command with the error terminated before executing completely. 

Request denied. The command was an undefined command. 



ADDITIONAL DISCUSSION 

"Executing Commands Programmatically" in Section V, 
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CREATE 

INTRINSIC NUMBER 100 



Creates a process. 

SYNTAX 



0-V BA BA I IV LV IV 
CREATE (prpgwame s entryname ^in ,param, flags y stacksize , 

IV IV LV IV 

dl size ,maxdata ^riorityclass ,rank ) ; 



If a running process, has Process Handling capability, it can request the creation of a son process by 
calling the CREATE intrinsic. The CREATE intrinsic loads the program to be run by the new process 
into virtual memory, creates the new process as the son of the calling process, initializes its data 
stack, schedules the process, and returns the new Process Identification Number (PIN) to the request- 
ing process. The CREATE intrinsic will achieve only partial completion if the circumstances described 
below exist. 

The process is not created and a PIN of zero is returned if one of the following conditions exist : 

• The stacksize is less than 5 1 2 (decimal) and is not - 1 . 

• The dlsize is less than and is not - 1 . 

• The maxdata is less than or equal to 0, and is not - 1 . 

• The stack space required exceeds maxdata. The dlsize may have been modified by the intrinsic to 
satisfy Condition 2 under CCG. The DB global size value is the sum of the primary DB plus the 
secondary DB values (found on the compiler listing) or the total DB given at program preparation 
time by the program map (PMAP). 

• An illegal value (a nonexistent subqueue) was specified for the priorityclass parameter. 
The process is not created and the PIN is unchanged if one of the following conditions exist : 

• The program file of the creating process does not have Process Handling (PH) capability. 

• A required parameter (progname or pin) is omitted. 

• A reference parameter was not within the required range . 

The request is granted and the process is created with maxdata allowed if: 

• The maxdata exceeds the configured maxdata, where maxdata is either the value passed as a pa- 
rameter, or a value recomputed by the Loader under Condition 1 of CCG. 

The request is granted and the process is created if : 

• The stack space exceeds the maximum stacksize defined during system configuration. The 
dlsize may have been modified to satisfy Condition 2 under CCG . 
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The request is denied and a PIN of zero is returned if : 

• The progname is illegal . 

• The entryname is illegal. 



PARAMETERS 

progname 

entvyname 



pin 



papain 



flags 



byte array (required) 

Contains a string, terminated by a blank, specifying the name, and option- 
ally, the account and group of the file containing the program to be run. 
If the program has a lockword , the lockword must be specified . 

byte array (optional) 

Contains a string, terminated by a blank, specifying the declared entry 
point (label) in the program where execution is to begin when the process is 
activated. The primary entry point in the program can be specified by set- 
ting the array equal to a blank character alone. 

Default : The primary entry point is used . 

integer (required) 

A word in which the PIN of the new process is returned to the requesting 
process. This PIN is used in other intrinsics to reference the new process. 
The PIN can range from 1 to 1024. If an error is detected, a PIN of zero is 
returned to the requesting process . 

integer by value (optional) 

A word used to transfer control information to the new process. Any in- 
struction in the outer block of code in the new process can access this in- 
formation in location Q-4 of the stack. 

Default: Word is filled with zeros. 

logical by value (optional) 

A word whose bits specify the loading options : 

Bit (15:1) -ACTIVE bit. 

=0 The calling process is not activated when the new process terminates. 

= 1 MPE reactivates the calling process (father) when the new process 
terminates. 

Default: (15: 1 )=0 
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Bit (14:1) -LOADMAPbit. 

=0 No map is produced . 

= 1 A listing of the allocated (loaded) program is produced on the job/ses- 
sion list device. This map shows the Code Segment Table (CST) entries 
used by the new process. 

Default: (14:1)=0 

Bit (13:1) -DEBUG bit. 

This bit is ignored if the user is nonprivileged and the new process requires 
Privileged Mode. It is also ignored if the user does not have read/write ac- 
cess to the program file of the new process . 

=0 The breakpoint is not set. 

= 1 DEBUG is called at the first executable instruction of the new process. 

Default: (13:1)=0 

Bit (12:1) -NOPRIVbit. 

=0 The program is loaded in the mode specified when the program file was 
prepared. 

= 1 The program is loaded in non-Privileged Mode. 

Default: (12:1)=0 

Bits (10:2) - LIBSEARCH bits. 

These bits denote which libraries are to be searched for the program. 

=00 Search the System Library. 

=0 1 Search the Account Public Library , followed by System Library . 

= 1 Search the Group Library first , then the Account Public Library , and 
finally the System Library. 

Default: (10:2)=00 

Bit (9:1) -NOCBbit. 

If you are using a large stack set (9: 1)=1 . 

=0 Control blocks may be established in the Process Control Block 
Extension (PCBX) area. 

= 1 The file system control blocks are established in an extra data segment. 
Default: (9:1)=0 
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stacksize 



dlsize 



mxxdata 



Bits (7:2) - These bits are reserved for MPE and should be set to zero. 

Bits (5:2) - STACKDUMP bits. 

These bits control the enabling/disabling of the mechanism by which the 

stack is dumped in the event of an abort . 

=00 Stackdump mechanism enabled only at father level. 

=01 Stackdump mechanism is enabled unconditionally. 

= 10 Same as (5:2)=00. 

= 11 Stackdump mechanism disabled unconditionally for new process. 

Default: (5:2)=00 

Bit (4:1) - Reserved for MPE and should be set to zero. 

Bit (3:1) - DL to QI bit. (This bit is used only when bits (5:2)=01 .) 

=0 This portion of the stack will not be dumped. 

= 1 Causes the portion of the stack from DL to QI to be dumped. 

Default: (3:1)=0 

Bit (0:3) - Reserved for MPE and used only when ( 5 : 2 )= 1 . 

integer by value (optional) 

An integer denoting the number of words assigned to the local stack area 
bounded by the initial Q and Z registers. A value of -1 indicates that the 
MPE Segmenter is to assign default values. Specifying - 1 is equivalent to 
omitting the parameter. 

Default: The same as that specified in the program file. 

integer by value (optional) 

An integer denoting the number of words in the user -managed stack area 

bounded by the DL and DB registers . A value of - 1 indicates that the MPE 

Segmenter is to assign default values. This is equivalent to omitting the 

parameter. 

Default: The same as that specified in the program file. 

integer by value (optional) 

The maximum size allowed for the process stack in words. When specified, 
this value overrides the one established at program preparation time. A 
value of -1 indicates that the MPE Segmenter is to assign default values. 

Default: If not specified in either the intrinsic call or the program file, 
MPE assumes that the stack will remain the same size . 
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priori tyclass logical by value (optional) 

A string of two ASCII characters describing the priority class in which the 
new process is scheduled. Standard users (nonprivileged) can reschedule 
processes into any of the five subqueues except the AS queue. However this 
function is limited by the maximum priority assigned to the account by the 
System Manager. Users who have Privileged Mode capability can schedule 
processes into the AS subqueue, as well as any of the others. A process in 
the linear queue AS or BS will not give up CPU voluntarily. Therefore, it 
could loop infinitely and prevent other processes from accessing the CPU. 

Default: The same as the priority of the calling process. 

rank integer by value (optional) 

This parameter is used only for backward -compatibility with pre-MPE IV 
operating systems. This parameter is ignored on versions G.00.00 and 
later. 

CONDITION CODES 

CCE Request granted. The new process has been created. 

CCG Request granted. The maxdata and/or dlsize parameters given were illegal, 

but other values were assigned as follows: 

1 . If the maxdata specified exceeds the maximum Z-DL allowed by the 
configuration , the configured maximum value is assigned . 

2. If the area from Base to DB is not zero, then the DL area pads this 
area to round it up to 128. 

CCL Request denied because the progname or entryname specified does not exist. 

SPECIAL CONSIDERATIONS 

Process Handling (PH) capability required. 

ADDITIONAL DISCUSSION 

"Creating an Extra Data Segment" and "Creating and Activating Processes" in Section III. 
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CREATEPROCESS 

INTRINSIC NUMBER 101 
Creates a process and can assign $STDINand $STDLISTto any file. 

SYNTAX 



0-V I I BA IA LA 

CREATEPROCESS terror, pin ,progname ,itemnwns , items ) ; 



CREATEPROCESS entails a superset of the CREATE intrinsic and is designed to be more flexible and ex- 
tendable than CREATE. The CREATEPROCESS intrinsic not only creates a process, it also allows you to 
assign the system-defined files, $STDINand SSTDLIST, to any file when the process is created. You 
are not limited to system -defined defaults for $STDIN and $STDLIST. If the intrinsic is called with 
the error parameter omitted, an invalid address for parameter error is returned. In split-stack mode, 
the calling process will be aborted . 

PARAMETERS 

error integer (required) 

An integer indicating type of success or failure. A minus sign (-) preceding 
the returned value indicates that the associated message is a warning. An 
error terminates the intrinsic call while a warning means the call will con- 
tinue. The Job Control Word (JCW) should be checked before continuing. 
The following is a list of the possible values returned : 

Message No . Meaning 

Process created as requested. 

1 Caller lacks Process Handling (PH) capability. 

2 Required parameter (other than error) omitted. 

3 Parameter address (other than error) out of bounds. 

4 Out of system resources (e.g. PCBs, DSTs). 

5 Process not created because an invalid itemnums was 
specified . 

6 Unable to create process because progname does not 

exist. 

7 Unable to create process because entry name does not ex- 
ist or is invalid. 

8 Process not created because progname is invalid . 

-9 Process created with default stacksize from the program 

file (specified stacksize was < 512). 
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■10 



Process was created with default dlsize from the 
program file (specified dlsize was < 0). 



•11 



Process created with default maxdata from the program 
file (specified maxdata was < 0). 



■12 



Process created with dlsize rounded up to next 128 -word 
multiple. 



•13 



Process created with maxdata decreased to configuration 
maximum . 



-14 



Process created with maxdata increased to dlsize+glob- 
size+stacksize (globsize is defined to be primary DB 
space+secondary DB space). 



15 



Process not created because dlsize+globsize+stacksize was 
> configured maximum stacksize . 



16 



Process not created because "hard" load error occurred 
(for example, I/O error reading the program file). 



17 



Process not created because an illegal value was specified 
for priority class. 



18 



Unable to create process because specified SSTDIN could 
not be opened. 



19 



Unable to create process because $STDLIST could not be 
opened. 



20 



Process not created because string to be passed to new 
process was invalid (pointer without length, length 
without pointer, or length exceeds stack size of calling 
process). 



jrvn 



integer (required) 

An integer in which the PIN of the newly created process is returned. If 
there is an error in creating the new process, i.e. parameter error > 0, a 
zero is returned . 



progname 



byte array (required) 

A byte array containing a string, terminated by any nonalphanumeric 
character other than a period (.) or a slash (/), which specifies the name of 
the program file to be run by the new process. 



itermums 



integer array (optional) 

An array containing the item numbers (in any order) of the options you 
want to use in creating a new process. This array must contain a zero as its 
last element to indicate the end of the option list. (Refer to Table 2- 1 .) 



items 



logical array (optional) 

An array containing the items (in the same order as the item numbers in 

itemnums), to be used in creating the new process. (Refer to Table 2-1.) 
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Table 2- 1 . Item Values Returned by CREATEPROCESS 



The Item Numbers in the array itemnums indicate the options to be applied in creating the new 
process. The corresponding items in the array items give the information necessary for each op- 
tion to be used. 

Itemnumber Items 

Indicates the end of the option list. 

1 A pointer to a byte array containing the name of the entry point in the program 
where the new process is to begin execution. The name is specified as a string of 
characters terminated by a blank. 

2 An integer containing a parameter to be passed to the new process (accessed 
through location Q-4 of the outer block). 

3 A logical value containing the load option flags to be used in loading the program 
file for the new process. This parameter has the same definition as the flags pa- 
rameter of the CREATE intrinsic . 

4 An integer specifying the initial stack size (Q-Z). 

5 An integer specifying the initial dlsize (DL-DB) for the new process. 

6 An integer specifying the maximum stack size for the new process (i.e. maxdata). 

7 A string of two ASCII characters specifying the priority class in which the new 
process is to be scheduled (AS, BS, CS, DS, or ES). Selecting AS or BScan cause 
performance degradation since the process will wholly own the CPU. 

8 A pointer to a byte array containing the definition of a file to be used as $STDIN 
for the new process . (See Notes 1 & 2 . ) 

9 A pointer to a byte array containing the definition of a file to be used as 
ISTDLISTfor the new process. (See Notes 1 & 3.) 

10 A logical value indicating that the process has suspended and its anticipated 
source of reactivation. Specification of this parameter causes the newly created 
process to be activated immediately. The meanings of the individual bit fields of 
this parameter are as follows : 

Bit (15:1) Father activation bit. 

= 1 The process expects to be activated by its father . 

=0 The process does not expect to be activated by its father. 

Bit (14:1) Son activation bit. 

= 1 The process expects to be activated by one of its sons. 

=0 The process does not expect to be activated by one of its sons. 

1 1 A pointer to a byte array containing a string of information to be passed to the 
new process. The length of the string is specified in Item Number 12. (See Note 
4.) 

12 An integer specifying the length in bytes of the string specified with Item 
Number 11. (See Note 4.) 
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Table 2- 1 . Item Values Returned by CREATEPROCESS (Continued) 



NOTES 

1. If Item Numbers 8 or 9 are not specified, the default $STDIN and $STDLIST will be used 
in creating the new process. These defaults are the current SSTDIN and SSTDLIST files 
for the creating (father) process. 

2. Item Number 8 indicates that the corresponding item in the item array is the address of a 
byte array which contains the definition of the file to be used as $STDIN for the new 
process. This byte array must contain an ASCII string (terminated by a carriage return) 
which is the right-hand side of a file equation specifying the file to be used as $STDIN 
(i.e. everything after the " :FILE formzldesignator=" portion of the file equation). 

3. Item Number 9 indicates that the corresponding item in the item array is the address of a 
byte array which contains the definition of the file to be used as SSTDLIST for the new 
process. This array is defined as above for $STDIN. 

4. Item Numbers 11 and 12 indicate that a string is to be passed to the new process. This 
string will be placed just after the global area of the new process stack. A DB relative 
value byte pointer to the string in the new process stack will be placed at the Q-5 of the 
stack (where Q is the initial value of the Q -register at activation time) and the length of 
the string in bytes will be placed at Q-6. If no string is specified to be passed to the new 
process, Q-5 and Q-6 will both contain 0. 



CONDITION CODES 

CCE No error. 

CCL Unsuccessful. 

CCG Successful call, however a warning might have been returned to error. 

SPECIAL CONSIDERATIONS 

Process Handling (PH) capability required. 

ADDITIONAL DISCUSSION 

"Creating and Activating Processes" in Section III. 
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CTRANSLATE 

INTRINSIC NUMBER 61 



Converts a string of characters between EBCDIC and ASCII, or between EBCDIK and JIS (KANA8). 

SYNTAX 



0-V IV BA BA IV BA 

CTRANSLATE (code, i7tstring 3 outstring,stringlength y table ) ; 



The CTRANSLATE intrinsic is used for character code translating. Translation can occur between the 
standard computer character codes or with an optional user-defined code permitting you to obtain 
character code conversions within programs of your own design. 

EBCDIK is a Hewlett-Packard-specific (Japanese) version of EBCDIC. 

KAN A 8 is an 8 -bit JIS (Japanese International Standard, JISCII, a Japanese version of US ASCII) 
code. 



PARAMETERS 

code 



instring 

outstring 

stringlength 



integer by value (required) 

An integer identifying a specific translation to be used as follows : 

The user-supplied table specified in the table parameter. 

1 EBCDIC to ASCII. 

2 ASCII to EBCDIC. 

3 Reserved for future use. 

4 Reserved for future use. 

5 EBCDIK to JIS (KANA8). 

6 JIS (KANA8) to EBCDIK. 

byte array (required) 

The string of characters to be translated . 

byte array (optional) 

A byte array to which the translated character string is returned. If an 
outstring is not specified, all translation will occur within instring. The in- 
string and outstring parameters may specify the same array . 

integer by value (required) 

A positive integer specifying the length (in bytes) of instring. 
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table byte array (required when code=0, otherwise optional) 

A byte array to be used as the translation table. The contents of table, and 
the order of these contents, define the translation process. The length of 
table may be as large as 256 bytes, but it needs to be only as large as the 
largest numeric value of any source byte in instring. The table array is con- 
structed such that each byte in table corresponds to a byte value in the 
source string to be translated. For example, the first byte in table gives the 
code to be substituted for source bytes whose value is 0. 

CONDITION CODES 

CCE Request granted. Translation performed successfully. 

CCG Not returned by this intrinsic. 

CCL Request denied because an error occurred. 

ADDITIONAL DISCUSSION 

"Translating Characters With the CTRANSLATE Intrinsic" in Section V. 
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DASCII 



INTRINSIC NUMBER 75 
Converts a double -word (32 -bit) binary number to an ASCII string. 

SYNTAX 



I DV IV BA 

numchar : = DASC I I (.dtiord,base ^string) j 



A 32-bit double-word binary number can be converted to a different base and represented as a 
numeric character ASCII string by issuing the DASC 1 1 intrinsic call . 



FUNCTIONAL RETURN 



numchar 



integer 

The number of characters in the resulting string. 



PARAMETERS 

daord 

base 



string 



double by value (required) 

A double -word value indicating the number to be converted to ASCII code. 

integer by value (required) 

One of the following integers indicating octal or decimal conversion : 

8 Octal conversion. 

1 Decimal conversion (left -justified ) . 

If any other number is entered in this parameter, the intrinsic causes the 
user process to abort . 

byte array (required) 

The byte array into which the converted value is placed. This array must 

be long enough to contain the result . No result will exceed 1 1 characters . 

For octal conversion (base=S), 11 characters, including leading zeros, are 
always returned in string , showing the octal representation of dword . The 
length (numchar) returned by DASC 1 1 is the number of significant (right - 
justified) characters in string, excluding leading zeros. If dword=0, the 
length returned by DASC 1 1 is 1. 

For decimal conversions (base= 10), dword is considered as a 3 2 -bit, two's 
complement integer ranging from -2,147,483,648 to +2,147,483,647. 
Leading zeros are removed and the result is left -justified in string. If the 
value of dword is negative, the first byte of the string returned contains a 
minus sign. If dword=0, only one is returned to string. The string array 
can contain up to 1 1 characters, including the sign. If dword=0, the length 
returned by DASCII is 1. 
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CONDITION CODES 

The condition code remains unchanged . 

ADDITIONAL DISCUSSION 

"Converting Numbers from Binary Code to ASCII Strings" in Section V. 
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DATELINE 

NO INTRINSIC NUMBER ASSIGNED 
Returns the current date and time . 

SYNTAX 



BA 
DATELINECdotefcu/); 



PARAMETERS 

datebuf byte array (required) 

A 2 7 -character byte array which contains the date and time information 
in the format : 

FRI, MAY 27, 1983, 12:06 PM 

CONDITION CODES 

The condition code remains unchanged. 

ADDITIONAL DISCUSSION 

None. 



2-40 



DBINARY 

INTRINSIC NUMBER 74 



Converts a number from an ASCII string to a double -word binary value. 

SYNTAX 



D BA IV 

doal : =DBW(\RY Qstving,length) ; 



FUNCTIONAL RETURN 

doal double (optional) 

The converted double-word binary value. 

PARAMETERS 

string byte array (required) 

Contains the octal or signed decimal number (in ASCII characters) to be 
converted. If the character string in this array begins with a percent sign 
(%), it is treated as an octal representation, if the string begins with a plus 
sign, a minus sign, or a number, it is treated as a decimal representation. 
Leading blanks are not allowed, and are treated as illegal characters. 

length integer by value (required) 

An integer representing the length (number of bytes) in the string contain- 
ing the ASCII-coded value. If the value of length is 0, the intrinsic returns 
to the calling process. If the value of length is less than 0, the intrinsic 
causes the user process to abort. 

CONDITION CODES 

CCE Successful conversion. A double-word binary value is returned to the 

program . 

CCG A word overflow, possibly resulting from too many characters {string 

number too large ) , occurred in the word returned . 

CCL An illegal character was encountered in string. For example, the digits 8 

or 9 were specified in an octal value. 

ADDITIONAL DISCUSSION 

"Converting Numbers from an ASCII Numeric String to a Binary Coded Value" in Section V. 
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DEBUG 

INTRINSIC NUMBER 99 
Invokes the DEBUG facility. 

SYNTAX 




PARAMETERS 

None. 

CONDITION CODES 

The condition code remains the same . 

ADDITIONAL DISCUSSION 

MPE Debug/Stack Dump Reference Manual (30000-90012). 
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DLSIZE 

INTRINSIC NUMBER 135 



Expands or contracts the area between DL and DB. 

SYNTAX 



i iv 

dldbsize : =DLS I ZE (.size ) ; 



This intrinsic causes the area between DL and DB to be expanded or contracted within the stack seg- 
ment. All current information within the area is saved on expansion. If contracting, data in the area 
which is to be contracted is lost. A request for contraction less than the initial DL size of the area 
causes the initial DL size to be granted and CCL to be returned. If the size requested causes the stack 
to exceed the maximum size permitted by the stack area (Z-DL), only this maximum is granted. 

All addressing within the DL-to-DB area is DB-relative "negative" indexing. Therefore, SPL is the 
only language which can access this area for you. If you wish to access this area in SPL, please note 
that the original data is not moved relative to DB on expansion or contraction of the area. For ex- 
ample, if a variable is located at DB-10 before an expansion, it will be at DB- 10 after the expansion. 

FUNCTIONAL RETURN 

dldbsize integer (optional) 

The size actually granted . This value is a negative quantity except on error 
condition CCL when it is possible toliave a positive value returned. 

PARAMETERS 

size integer by value (required) 

A negative integer representing the new size of the DL-to-DB area. A size 
of is permitted and resets the DL-to-DB area to the original value assign- 
ed when the process was created (initial DL) . (This is the only way to con- 
tract the DL-to-DB area.) The size granted will be an absolute value 
which is rounded up so that the distance between the beginning of the seg- 
ment and DB is a multiple of 1 28 words. 

CONDITION CODES 

CCE Request granted. The value returned is at least as large as the value 

requested . 

CCG Requested size exceeded maximum limit allowed. The maximum limit al- 

lowable is granted and its size is returned . 

CCL An illegal size parameter was specified. The size parameter was a positive 

integer. The original area size, assigned when the stack segment was 
created, is granted. 
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ADDITIONAL DISCUSSION 

"Changing the DL to DB Area Size" in Section V. 
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DMOVIN 

INTRINSIC NUMBER 132 



Copies data from an extra data segment into the stack. 

SYNTAX 



LV IV IV LA 

DMOVIN (index >disp ,number , location') ; 



A process can copy data from an extra data segment into the stack by issuing the DMOVIN intrinsic 
call. A bounds check is initiated by the intrinsic on both the extra data segment and the stack to en- 
sure that the data is taken from within the data segment boundaries and moved to an area within the 
stack boundaries. For example, in the diagram shown below, to move four words from locations 422 
through 425 of the data segment whose index is 21, to DB+40 through DB+43 of the stack, the in- 
trinsic call would be : 

DM0VINC21 , 422,4, ARAC10)); 

The index is 21 (refer to GETDSEG); displacement (disp) within the data segment is 422; the number 
of words to move into the stack is 4 ; and the DB relative location to begin transferring the data is the 
address of ARAC1 0). If ARAC1 0) is at DB+40, the end result will be the four words moved to DB+40 
through DB+43 within the stack, as shown below: 



STACK 



DL 
DB 






" 


ARA(O) 




ARA(1) 




; 


ARA (10) DB+40 


042503 


41 


045501 


42 


047113 


43 


040522 


Q 
S 

Z 





DATA SEGMENT 
(GETDSEG INDEX=21) 



<r 



u 




422 


042503 


423 


045501 


424 


047113 


425 


040522 


12000 
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PARAMETERS 

index 
disp 

number 
location 



logical by value (required) 

A word containing the logical index of the extra data segment, obtained 

from a GETDSEG intrinsic call. 

integer by value (required) 

The displacement of the first word in the string to be transferred from the 
first word in the data segment. This must be an integer value greater than 
or equal to zero. 

integer by value (required) 

The size of the data string to be transferred, in words. This must be an in- 
teger value greater than or equal to zero. 

logical array (required) 

The array (buffer) in the stack where the data string is to be moved. 



CONDITION CODES 

CCE Request granted. 

CCG Request denied because of bounds-check failure. 

CCL Request denied because of illegal index or number parameter. 

SPECIAL CONSIDERATIONS 

Data Segment Management (DS) capability required. 

ADDITIONAL DISCUSSION 

The GETDSEG intrinsic in this section , and "Creating an Extra Data Segment " in Section III . 
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DMOVOUT 

INTRINSIC NUMBER 133 



Copies data from the stack to an extra data segment . 

SYNTAX 



LV IV IV LA 

DMOVOUT (index ,disp 3 rtumber , location ) ; 



The DMOVOUT intrinsic copies data from the stack to an extra data segment. When DMOVOUT is called, 
a bounds check is initiated to ensure that the data is taken from an area within the stack boundaries 
and moved to an area within the extra data segment boundaries. For example, in the diagram shown 
below, to move four words from ARAC10) within the stack to the data segment whose index is 2 
(from a GETDSEGcall), starting at location 201 within the segment, the intrinsic call could be: 

DMOVOUT C2,201,4,ARA(10)); 

The index is 2; the displacement (disp) within the data segment is 201; the number of words to be 
moved to the data segment is 4; and the location of the data within the stack is the address of 
ARAC10). If ARAC10) is at DB+20, the end result is that the four words within the stack will be 
moved to words 201 through 204 of the data segment, as shown below: 



DL 
DB 


STACK 






'. 


ARA(O) 




ARA(1) 




'. 


DB+20 


054517 
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PARAMETERS 

index 

disp 

number 
location 



logical by value (required) 

A word containing the logical index of the extra data segment, obtained 

from a GETDSEGcall. 

integer by value (required) 

The displacement, in the extra data segment, of the first word of the 
receiving buffer from the first word in the data segment. This value must 
be an integer greater than or equal to zero. 

integer by value (required) 

The size of the data string to be transferred, in words. This must be an in- 
teger value greater than or equal to zero. 

logical array (required) 

The array (buffer) in the stack containing the data to be moved. 



CONDITION CODES 

CCE Request granted . 

CCG Request denied because of bounds -check failure. 

CCL Request denied because of illegal index or number parameter. 

SPECIAL CONSIDERATIONS 

Data Segment Management (DS) capability required. 

ADDITIONAL DISCUSSION 

The GETDSEG intrinsic in this section, and "Creating an Extra Data Segment" in Section HI. 
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ENDLOG 

NO INTRINSIC NUMBER ASSIGNED 



Marks the end of a user logging transaction. 

SYNTAX 



D LA I I I 

ENDLDG(index,dcrta, ten , mode , status ) ; 



The ENDLOG intrinsic posts a special record to the logging file to mark the end of a logical transaction 
in the logging file. When the record is posted, ENDLOG flushes the user logging memory buffer to en- 
sure that the record gets to the logging file . 

The data parameter of this intrinsic can be used to post user data to the logging file. This function of 
the procedure is identical to the WR I TELOG intrinsic. 



PARAMETERS 

index 

data 



len 



mode 



status 



double (required) 

The parameter returned from OPENLOG that identifies the user's access to 

the logging file. 

logical array (required) 

An array in which the actual information to be logged is passed. A log 
record contains 128 words of which 1 1 9 words are available to the user . 
Thus , the most efficient use of logging file space is to structure arrays with 
lengths in multiples of 1 1 9 words. 

integer (required) 

The length of the data in data. A positive count indicates words and a 
negative count indicates bytes. If the length is greater than 1 19 words, the 
information in data will be divided into two or more physical log records. 

integer (required) 

An integer which specifies whether you want your process impeded by the 
logging process if the logging buffer is full. If it is not possible to log the 
transaction and the mode is set to NOWAIT, the ENDLOG intrinsic will 
return an indication in the status word that the request was not completed : 

Specifies WAIT. 

1 Specifies NOWAIT. 

integer (required) 

One of the following integers that the logging system uses to return infor- 
mation on the status of the intrinsic call : 
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Message No . Meaning 

No error occurred for this call. 

1 User requested NO WAIT mode and the logging process is 
busy. 

2 Parameter out of bounds in logging intrinsic . 

3 Request to open or write to a logging process that is not 
running . 

4 Incorrect index parameter passed to a logging intrinsic. 

5 Incorrect mode parameter passed to a logging intrinsic . 

6 User request denied because logging process is suspended. 

7 Illegal capability. Must have User Logging (LG) and 
System Supervisor (OP) capabilities to use a logging 
intrinsic. 

8 Incorrect password passed to a logging intrinsic. 

9 Error occurred while writing to the logging file. 

1 Invalid DST passed to a logging system intrinsic. 

1 2 System is out of disc space, logging cannot proceed. 

1 3 No more logging entries. 

1 4 Invalid access to logging file . 

1 5 End -of -file on user logging file. 

1 6 Invalid logging identifier. 



CONDITION CODES 

The condition code remains unchanged. 

SPECIAL CONSIDERATIONS 

User Logging (LG) and System Supervisor (OP) capabilities required. 

ADDITIONAL DISCUSSION 

"User Logging" in Section III. 
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EXPANDUSLF 

INTRINSIC NUMBER 84 



Changes length of a USL file . 

SYNTAX 



I IV IV 

filenum: =EXPANDUSLFCusZ/nwn?,records) ; 



You can increase or decrease the length of a USL file by calling the EXPANDUSLF intrinsic. When this 
intrinsic is executed, a new USL file is created with a records length longer or shorter than the USL 
file specified by uslfnum. The old USL file is copied to the new file with the same file name; the old 
USL file is then deleted. 

FUNCTIONAL RETURN 

filenum integer (optional) 

The new file number. If an error occurs, the error number is returned in- 
stead of the new file number ; the condition code must be tested immediate- 
ly on return from this intrinsic. If an error number were to be used as a 
file number, unpredictable results would occur. The following lists the er- 
ror numbers and their associated meanings : 

Error No . Meaning 

The file specified by uslfnum was empty , an unexpected 
end-of-file was encountered when reading the old USL 
file, or an unexpected end-of-file was encountered 
when writing the new uslfnum. 

1 Unexpected input/output error occurred. This can oc- 
cur on the old USL file, or the new uslfnum to which 
the intrinsic is copying the information. 

7 The intrinsic was unable to open the new USL file . 

8 The intrinsic was unable to close (purge) the old USL 
file. 

9 The intrinsic was unable to close (save) the new USL 
file. 

1 The intrinsic was unable to close $NEWPASS. 

1 1 The intrinsic was unable to open SDLDPASS. 
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PARAMETERS 

uslfnum integer by value (required) 

A word supplying the file number of the file. 

records integer by value (required) 

A signed integer specifying the number of records by which the length of 
the USL file is to be changed. If records is a positive value, the new USL 
file is longer than the old USL. If records is a negative value, the new USL 
file is shorter than the old USL. 

CONDITION CODES 

CCE Request granted. The new file number is returned . 

CCG Not returned by this intrinsic. 

CCL Request denied . An error number was returned to filenum . 

ADDITIONAL DISCUSSION 

MPE Segmenter Reference Manual (30000-9001 1). 
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FATHER 

INTRINSIC NUMBER 109 



Requests the Process Identification Number (PIN) of its father process. 

SYNTAX 



i 

pin :=FATHER; 



A process can determine the Process Identification Number (PIN) of its father by calling the FATHER 
intrinsic . 

FUNCTIONAL RETURN 

pin integer 

An integer containing the Process Identification Number (PIN) for the 
father of the process. 

CONDITION CODES 

CCE Request granted. The father is a user process. 

CCG Request granted. The father is a job or session main process . 

CCL Request granted. The father is a system process . 

SPECIAL CONSIDERATIONS 

Split-stack calls permitted. 

Process Handling (PH) capability required. 

ADDITIONAL DISCUSSION 

"Determining Father Process" in Section III. 
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FCARD 

NO INTRINSIC NUMBER ASSIGNED 

Drives the HP 7260A Optical Mark Reader (OMR). 

SYNTAX 



I I IA I I 

FCf\RDir^code 9 filertiim s bufadx' s count y stattis^- 1 



The FCARD intrinsic allows you to control the operation of the Optical Mark Reader (OMR) 
programmatically. This is achieved through passing a parameter (recode), corresponding to the func- 
tion of FCARD desired, from your program to FCARD. FCARD returns to the program parameter values 
which indicate the success or the cause of failure of execution, the status of the HP 7260A, the file 
number of the HP 7260A/terminal file for which the function has been performed and the number of 
columns read at the completion of a read request. 

PARAMETERS 

recode integer (required) 

A positive integer represented as an input or output parameter. 

As an input parameter, recode requests one of the following options 
(functions) : 

Open the reader and terminal as a file and return the filenum to the 
program through SPL/ 3000 conventions. 

1 Read a single card whether in ASCII or in column image format. 

2 Select the previously read card by routing the card into the select 
output hopper (providing option 002 of the HP 726 0A is installed). 

3 Retransmit data from the previously read card. This transmission 
may be performed in ASCII or column image reading formats, 
depending on the latest FCARD call issued specifying recode equal to 
11 or 12. 

4 Temporarily suspend the program awaiting an operator action (press 
the READY switch). This particular call to FCARD will maintain 
control and will not be completed until the operator presses the 
READY switch. 

1 Cause the HP 7260A motor to come to a stop and deactivate MUTE 
for the associated terminal, if muted. When MUTE is activated and 
the HP 7260A is in its READY state, data transmission from the 
computer and from the HP 7260A to the terminal is disabled. 
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1 1 Cause the output format of the subsequent read (recode= 1 ) and 
retransmit {recode-3) requests to be performed in the image reading 
format. In image mode reading, count is returned to the program 
with the number of columns which have been transmitted. 

1 2 Cause the output format of the subsequent read (recode= 1 ) requests to 
be performed in the ASCII reading format. In ASCII mode reading, 
count, is returned to the program with the number of characters 
(columns) transmitted. 

1 3 Cause the optional bell to ring (providing option 004 is installed). 

17 Enable the "echo-on" function of the computer. 

1 8 Disable the "echo -on" function of the computer. 

20 Close the reader /terminal file opened with recode=0. This effectively 
completes the program. 

As an output parameter, recode indicates to the program whether a call to 
FCARD has been properly executed. The indication given by the value of 
recode is described below : 

Indicates that the request, i.e. the call to FCARD, has been successful- 
ly performed. For the following conditions, when output recodcO, 
the specified parameters are significant to the program: 

a. If the request was to open a file (recode-0), then filenum is 
significant. 

b. If the request was either to read (recode=l) or to retransmit 
(recode=2), then bufadr (the first byte may contain status infor- 
mation identical to that contained in the parameter status), 
count, filenum, and status are significant. 

c. If the request was to select the previously read card (recode=2), 
then status is significant. 

d. If the request was to perform a temporary suspension of the 
program (recode=4), then status is significant. 

e. For all other requests {recode* 10, 1 1 , 12, 17, 18, and 20), none 
of the other parameters are significant . 

1 Indicates that recode specified in the request was not one of the fol- 
lowing legal values: 1, 2, 3, 4, 10, 11, 12, 13, 17, 18, or 20. 

2 Indicates that FCARD was unable to open the HP 7260A/terminal pair 
as a file. This error is not recoverable; the program should indicate 
an error and terminate itself. 

4 Indicates that FCARD has encountered a file read or write error while 
accessing the HP 7260A. This error is not recoverable; the program 
should indicate an error and proceed to a normal termination. 
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filenum 



bufadp 



count 



status 



5 Indicates that FCARD was unable to close the terminal file. This error 
is not recoverable; the program should indicate an error and proceed 
to a normal termination . 

6 Indicates that a logical end-of-data ( : JOB, :E0J, :EOD, and :DATA) 
was encountered while reading data in response to either a read or 
retransmit request. 

7 Indicates that FCARD has encountered a file error on a request for 
either enabling or disabling the echo function . 

8 Indicates that FCARD has detected a data dropout condition while the 
HP 7 260 A was transmitting. You should request a retransmission of 
the data or status (refer to recode=3). 

integer (required) 

A word supplying the file number of the file associated with the 

reader/terminal file. This file number is returned to the program from 

FCARD with the output recode=0. It must be provided to FCARD on all 

requests. 

integer array (required) 

The array to which the record is to be transferred. The declared length of 

bufadr should be set to 1 20 words. 

integer (required) 

A positive integer which is returned to the program upon completion of a 
read (recode=l) or a retransmit (recode =/ i) request indicating the number of 
columns which have been transferred from the HP 7260A. 

integer (required) 

An integer indicating whether the HP 7260A has successfully performed or 
responded to the read, select, retransmit, or temporary suspend request. If 
status is equal to zero, then the request has been successfully performed. If 
status is not equal to zero , then it contains an octal value specifying the HP 
7260A condition. The octal values indicate the following conditions: 



OCTAL 07 Input hopper empty or hopper full. Can either be 

returned upon a read request (recode=\) or upon a 
retransmit request, if there is no data to retransmit 
(recode=3). 

OCTAL 1 1 Pick fail. Can either be returned upon a read request 

(recode=\) or upon a retransmit request, if there is no 
data to transmit (recode=3). 

OCTAL 13 Select hopper full. Indicates that the OMR select hopper 

was full when the select request (recode=2) was issued. 
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OCTAL 14 Successful select. Indicates that the HP 7260A has suc- 

cessfully selected the card upon the select request 
(recode=2). 

OCTAL 22 READY status. Indicates that the HP 7260A READY 

push button has been pressed (recode=4). Would also in- 
dicate that the HP 7260A is ready but there is no data to 
be retransmitted input (recode=3). 

OCTAL 37 Not ready. Can either be returned upon a read request 

(recode=l) or upon a retransmit request (recode-i). This 
status is provided by the HP 7260A if the operator has 
pressed the STOP button or if a lamp has burned out in 
the read head. 

FCARD derives the parameter status by assigning the contents of the first 
byte of bufadr to status, if this byte equals one of the values of status 
given above: after a read (recode=l), select (recode=2) or retransmit 
(recode=l) request, or if this byte equals octal 22 after a request for tem- 
porary suspension of the program {recode=4). 

For more details on the OMR status parameter, refer to the HP 7260A 
Operating and Service Manual (07260-90001). 



CONDITION CODE 

The condition code remains unchanged . 

ADDITIONAL DISCUSSION 

Appendix B, "DEVICE CHARACTERISTICS". 
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FCHECK 

INTRINSIC NUMBER 10 
Requests details about file input /output errors. 

SYNTAX 



0-V IV I I D I 
FCHECKifilenum, errorcode , tlog ,blknum,numrecs ) ; 



When a file intrinsic returns a condition code indicating an input/output error, additional details may 
be obtained by using the FCHECK intrinsic call. This intrinsic applies to files on any device. 

FCHECK accepts zero as a legal filenum parameter value. When zero is specified, the information 
returned in errorcode reflects the status of the last call to FOPEN. When FDPEN fails, there is no file 
number which can be referenced in filenum. Therefore when FDPEN fails, a filenum of zero can be 
used in the FCHECK intrinsic call to obtain the errorcode only. 



PARAMETERS 

filenum 

errorcode 



tlog 



blknum 



numrecs 



integer by value (optional) 

A word supplying the file number of the file for which error information is 

to be returned. If omitted or 0, FCHECK assumes you want the last FOPEN 

error. 

integer (optional) 

A word to which a 1 6 -bit code specifying the type of error that occurred is 
returned. If the previous operation was successful or an EOF was encoun- 
tered, all bits are set to zero. (Refer to Table 2-2 for a listing of File 
System Error Codes.) 

Default : The error code is not returned . 

integer (optional) 

A word to which the transmission log value recorded on the last data trans- 
fer is returned. This word specifies the number of words actually read or 
written if an input/output error occurred. 

Default: The transmission log value is not returned. 

double (optional) 

The physical record count if the file is not a spoolf ile ; or the logical record 
count if the file is a spoolf ile . The physical count is the number of physical 
records transferred to or from the file since either FOPEN, for fixed and 
undefined length record files; or the last rewind, rewind/unload, space 
forward or backward to tape mark, for variable length record files. 

integer (optional) 

A word to which the number of logical records in the bad block (blocking 

factor) is returned. 

Default : The number of logical records is not returned . 
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Table 2-2. File System Error Codes 



Code 
(Decimal) 



Meaning 





1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

16 

17 

18 

19 

20 

21 

22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

40 

41 

42 

43 

44 

45 

46 

47 



Successful (no errors) or end -of -file (EOF). 

Illegal DB register setting (typically , a request in split-stack mode when 

it is illegal) . 

Illegal capability. 

Required parameter is missing. 

Disc space allocation disabled on all discs in domain. 

DRT number >511. 

Device has no available spare blocks. 

Unformatted or uninitialized media on device. 

Illegal parameter value . 

Invalid file type specified in f options. 

Invalid record size specification. 

Invalid resultant block size. 

Record number out of range. 

Can't open file multiaccess, out of FMAVT entries. 

More than 255 opens of a file. 

Magnetic tape runaway . 

Device powered up . 

Forms control was reset. 

Invalid operation. 

Data parity error. 

Software time-out. 

End-of-tape. 

Unit not ready. 

No write-ring on tape. 

Transmission error. 

I/O time-out. 

Timing error or data overrun. 

Start I/O (SIO) failure. 

Unit failure. 

End -of -line (EOL) special character terminator. 

Software abort of input/output operation. 

Data lost. 

Unit not online. 

Data -set not ready. 

Invalid disc address. 

Invalid memory address. 

Tape parity error . 

Recovered tape error . 

Operation inconsistent with access type . 

Operation inconsistent with record type. 

Operation inconsistent with device type. 

Write exceeds record size . 

Update at record zero. 

Privileged file violation . 

Out of disc space . 

Input/output error on a file label. 
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Table 2-2. File System Error Codes (Continued) 



Code 
(Decimal) 



Meaning 



48 

49 

50 

51 

52 

53 

54 

55 

56 

57 

58 

59 

60 

61 

62 

63 

64 

65 

66 

67 

68 

69 

70 

71 

72 

73 

74 

76 

77 

78 

79 

80 

81 

82 

83 

84 

85 

86 
87 
88 
89 
90 
91 
92 
93 
94 



Invalid operation due to multiple file access. 

Unimplemented function. 

Nonexistent account . 

Nonexistent group. 

Nonexistent permanent file. 

Nonexistent temporary file. 

Invalid file reference. 

Device unavailable. 

Invalid device specification. 

Out of virtual memory. 

No passed file. 

Standard label violation. 

Global RIN not available. 

Out of group disc space. 

Out of account disc space. 

User lacks non-sharable device capability. 

Program not prepped with multiple RIN capability. 

Punch hopper empty . 

Plotter limit switch reached. 

Paper tape error. 

Insufficient system resources. 

I/O error. 

I/O error while printing header /trailer . 

Too many files open. 

Invalid file number. 

Bounds violation. 

No room left in stack segment for another file entry. 

Input buffer absent in IOWAIT. 

NOW AIT input/output operation is pending. 

No NO WAIT I/O pending for any file. 

No NOWAIT I/O pending for any special file . 

Spoolfile size exceeds configuration. 

No SPOOL class defined in system . 

Insufficient space in SPOOL class to honor this input/output request . 

I/O error on spoolfile. 

Device unavailable for spoolfile. 

Operation is inconsistent with spooling, (e.g. attempt to read hardware 

status). 

Spooling internal error . 

Bad spoolfile block . 

Nonexistent spoolfile. 

Power failure. 

Exclusive violation: file being accessed. 

Exclusive violation: file accessed exclusively. 

Lockword violation. 

Security violation. 

User is not creator. 
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Table 2-2. File System Error Codes (Continued) 



Code 
(Decimal) 



Meaning 



95 

96 

97 

98 

99 

100 

101 

102 

103 

104 

105 

106 

107 

108 

109 

110 

111 

112 

113 

114 

115 

116 

117 

118 

119 

120 

121 

122 

123 

124 

125 

126 

127 

128 

129 

130 

131 

132 

133 

134 

137 

138 

139 

148 

149 

150 

151 



Read not completed due to BREAK. 

Disc I/O error. 

No CONTROL- Y PIN. 

Read time overflow. 

BOT and backspace tape. 

Duplicate permanent file name. 

Duplicate temporary file name. 

I/O error on directory. 

Permanent directory overflow. 

Temporary directory overflow. 

Bad variable block structure. 

Extent size exceeds maximum. 

Insufficient space for user labels. 

Invalid file label. 

Invalid carriage control. 

Attempt to save permanent file as temporary. 

User lacks Save Files (SF) capability. 

User lacks Private Volumes (UV) capability. 

Volume set not mounted - mount problem . 

Volume set not dismounted - dismount problem. 

Attempted rename across volume sets rejected. 

Invalid tape label F0PEN parameters. 

Attempt to write on an unexpired tape file. 

Invalid header or trailer tape label. 

I/O error positioning tape for tape labels. 

Attempt to write IBM standard tape label. 

Tape label lock word violation. 

Tape label table overflow. 

End of tape volume set. 

Attempt to append labeled tape. 

Expiration date can't be later than that of preceding file. 

Character set number must be between and 3 1 . 

Form number must be between and 3 1 . 

Logical page number must be between and 3 1 . 

Vertical format number must be between and 3 1 . 

Number of copies must be between 1 and 32767. 

Number of overlays must be between 1 and 8 . 

Page length parm must be between 12 (=3") and 68 (=17" 

Picture number must be between and 3 1 . 

Extended capability parm must be (OFF) or 1 (ON). 

Defective track on foreign disc. 

Track does not exist on foreign disc. 

Deleted record on IBM diskette. 

Inactive RIO record . 

Missing item number or return variable . 

Invalid item number. 

Undefined file type. 
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Table 2-2. File System Error Codes (Continued) 



Code 
(Decimal) 



Meaning 



152 
153 
154 
155 
156 
157 
158 
159 
160 
161 
162 
163 
164 
165 
166 
167 
168 
170 

171 
172 
173 
174 
175 
176 
177 
178 
179 
180 

181 
182 
183 
184 
185 
186 
187 
188 
189 
190 
191 

192 
193 
194 
195 
196 



Unrecognized key word in FDPEN device parameter . 

Expecting " ;" or "carriage return" in FDPEN device parameter. 

Environment file open error. 

File not environment file. Check file code or record size. 

Header record incorrect. 

Uncompiled environment file. 

Error reading environment file. 

Error closing environment file . 

Error doing FDEVICECONTRDLfrom environment file. 

Too many parameters in device string overflow . 

Expecting "=" after keyword in device parameter. 

" ENV" backref erence in file equation incorrect . 

The device parameter too large or missing carriage return . 

Invalid density specification. 

FF I LE INFO failed in accessing remote spoolfile. 

Spoolfile label error, can't insert environment file name. 

Item not supported on remote system. 

The record is marked deleted. FPD I NT positioned pointer to a record that 

was marked for deletion. 

Duplicate key value (KSAM error). 

No such key (KSAM error). 

The tcount parameter larger than record size (KSAM error). 

Cannot get extra data segment (KSAM error). 

Internal KSAM error. 

Illegal extra data segment (KSAM error). 

Too many extra data segments for this process (KSAM error) . 

Not enough virtual memory for extra data segment (KSAM error). 

File must be locked before issuing this intrinsic (KSAM error). 

The KSAM file must be rebuilt because this version of KSAM does not 

handle the file built by previous version. 

Invalid key starting position (KSAM error). 

File is empty (KSAM error). 

Record does not contain all keys (KSAM error). 

Invalid record number (KSAM FF I NDN intrinsic error). 

Sequence error in primary key (KSAM error). 

Invalid key length (KSAM error). 

Invalid key specification (KSAM error). 

Invalid device specification (KSAM error). 

Invalid record format (KSAM error). 

Invalid key blocking factor value (KSAM error). 

Record does not contain search key for deletion . Specified key value 

points to record which does not contain that value (KSAM error) . 

System failure occurred while KSAM file was opened. 

$STDIN/$STDLI ST cannot be redirected to KSAM files. 

KSAM files not allowed for global AFTs. 

Global files cannot be remote files. 

Language not supported (KSAM error). 



2-62 



Table 2-2. File System Error Codes (Continued) 



Code 
(Decimal) 



Meaning 



197 
198 
201 
202 
203 
204 
205 
212 
214 

216 
217 
221 
240 
241 
242 
243 
244 
245 
246 
247 
248 
249 
250 
251 

252 
253 

254 
255 
302 
303 
304 
305 
306 
307 
308 
309 
310 
311 
312 



Native language internal error (KSAM error). 

Invalid version number in KSAM file (KSAM error) . 

Invalid ID sequence. 

Invalid telephone number (CS error). 

No telephone list specified (CS error). 

Unable to allocate an extra data segment for DS/DSN 3000. 

Unable to expand the DS/DSN 3000 extra data segment. 

File number returned from IOWA IT is not a DS line number. 

The requested DS line has not been opened with a user :DSLINE 

command . 

Message rejected by remote computer (DS error). 

Insufficient amount of user stack available (DS error). 

Invalid DS message format (Internal DS error). 

Local Communication line not opened by operator (DS error). 

DS line in use exclusively or by another subsystem . 

Internal DS software malfunction. 

Remote computer not responding (DS error) . 

Communications interface error. Remote Computer reset the line. 

Communications interface error. Receive time-out. 

Communications interface error. Remote computer has disconnected. 

Communications interface error. Local time-out. 

Communications interface error. Connect time-out. 

Communications interface error. Remote computer rejected connection. 

Communications interface error. Carrier lost. 

Communications interface error. The local data set for the DS line went 

"not ready". 

Communications interface error. Hardware failure. 

Communications interface error. No response to dial request by the 

operator . 

Communications interface error. Invalid input/output configuration. 

Communications interface error. Unanticipated condition. 

Invalid item number for FDEVICECDNTROL. 

Invalid access for item number to FDEVICECDNTROL. 

Attempt to change terminal parity in 8-bit mode. 

Invalid format in terminal configuration file. 

Checksum error in terminal configuration file. 

Passed value to FDEVICECDNTROL less than minimum. 

Passed value to FDEVICECONTRQL greater than maximum. 

Passed value to FDEVICEC0NTR0L is unsupported. 

Count to FDEVICECDNTROL insufficient to return information. 

Count to FDEVICECDNTROL greater than available store information. 

Passed special character has previously defined function . 
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CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied because filenum was invalid or a bounds violation occurred 

while processing this request (errorcode is 73). 

SPECIAL CONSIDERATIONS 

Split -stack calls permitted. 

ADDITIONAL DISCUSSION 

None. 
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FCLOSE 

INTRINSIC NUMBER 8 



Closes a file. 

SYNTAX 



IV IV IV 

FCLDSE (fiteman, disposition, seccode~) ; 



The FCLOSE intrinsic terminates access to a file . This intrinsic applies to files on all devices . FCLDSE 
deletes buffers and control blocks through which the user process accessed the file. It also deallocates 
the device on which the file resides and it may change the disposition of the file. If you do not issue 
FCLOSE calls for all files opened by your process , such calls are issued automatically by MPE when the 
process terminates. All magnetic tape files are left offline after such FCLOSE calls, to indicate to the 
System Operator that they may be removed. 

The FCLDSE intrinsic can be used to maintain position when creating or reading a labeled tape file 
that is part of a volume set. If you close the file with a disposition code of 3, the tape does not 
rewind, but remains positioned at the next file. If you close the file with a disposition code of 2, the 
tape rewinds to the beginning of the file but is not unloaded,. A subsequent request to open the file 
does not reposition if the sequence (seq) subparameter of formmsg in FOPEN specifies NEXT or 
default (1). A disposition code of 1 (rewind and unload) implies the close of an entire volume set. 

If an unlabeled magnetic tape is closed with a disposition code of 0, 1 , or 4, and the tape was written 
to while open, FCLDSE writes three EOFs at the end of the tape before performing a rewind or 
rewind/unload . This ensures that all tapes have an acceptable number of EOF marks at the end . The 
three EOFs are written only after the last FCLOSE to occur before the rewind , and only if the tape 
was written on. (This feature applies to version G. 01 .00 or later only.) 

For circular files, deletion of disc space beyond the end-of-file is not allowed. 

PARAMETERS 

filenum integer by value (required) 

A word supplying the file number of the file to be closed. 

disposition integer by value (required) 

Indicates the disposition of the file, significant only for files on disc and 
magnetic tape (disposition is ignored by the Foreign Disc Facility). This 
disposition can be overridden by a corresponding parameter in a :FILE 
command entered prior to program execution. The disposition options are 
defined by the bit fields (13:3) and (12:1) as follows: 

(13:3) - Domain Disposition . 

=000 No change. The disposition remains as it was before the file was 
opened. Thus, if the file is new, it is deleted by FCLOSE; other- 
wise, the file is assigned to the domain it belonged to previously. 
An unlabeled tape file is rewound. If the file resides on a labeled 
tape , the tape is rewound and unloaded . 
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=001 Permanent file. If the file is a disc file, it is saved in the system 
file domain . A new or old temporary file on disc will have an entry 
created for it in the system file directory. Should a file of the same 
name already exist in the directory, an error code is returned and 
the file remains open. If the file is an old permanent file on disc, 
this domain disposition has no effect. Also, if the file is stored on 
magnetic tape , the tape is rewound and unloaded . 

=010 Temporary job file (rewound). The file is retained in the user's 
temporary (job/session) file domain and can be requested by any 
process within the job/session. If the file is a disc file, the unique- 
ness of the file name is checked. Should a file of the same name al- 
ready exist in the temporary file domain , an error code is returned 
and the file remains open. When a file resides on unlabeled mag- 
netic tape, the tape is rewound. However, if the file resides on 
labeled magnetic tape, the tape is backspaced to the beginning of 
the presently opened file. 

=01 1 Temporary job file (not rewound). This option has the same effect 
as domain disposition 010, except that tape files are not rewound. 
In the case of unlabeled magnetic tape, if this FCLDSE is the last 
done on the device (with no other F0PEN calls outstanding) the tape 
is rewound and unloaded. If the file resides on a labeled magnetic 
tape, the tape is positioned to the beginning of the next file on the 
tape. 

= 100 Released file. The file is deleted from the system . 

(12:1) - Disc Space Disposition (for fixed, undefined, and variable format 
files. 

=0 Does not return any disc space allocated beyond the end-of-file 
indicator. 

= 1 Returns any disc space allocated beyond the end-of-file indicator to the 
system. The EOF becomes the file limit. No records may be added to 
the file beyond this new limit. 

Bit (0:12) - Reserved for MPE and should be set to zero. 

When a file is opened by the F0PEN intrinsic , a file count (maintained by 
MPE for each file) is incremented by one. When the file is closed, the file 
count is decremented by one. If more than one FDPEN is in effect for a 
particular file , its disposition is saved but not affected by the FCLDSE call 
until the file count is decremented to zero. Then the effective (saved) 
disposition is the smallest nonzero disposition parameter specified among all 
FCLDSE calls issued against the file. For example, the file XYZ is opened 
three successive times by a process. The first FCLDSE disposition is 1 , the 
second FCL0SE disposition is %14, and the third (and last) FCLDSE disposi- 
tion is %12. The final disposition on the file XYZ will be disposition 1 
(permanent file and no return of disc space). 
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secoode integer by value (required) 

Denotes the type of security initially applied to the file. This is significant 
only for new permanent files (seccode is ignored by the Foreign Disc 
Facility). The options are : 

Unrestricted access. The file can be accessed by any user, unless 
prohibited by current MPE provisions. 

1 Private file creator security. The file can only be accessed by its 
creator. 

CONDITION CODES 

CCE The file was closed successfully . 

CCG Not returned by this intrinsic. 

CCL The file was not closed because an incorrect filenum was specified or be- 

cause another file with the same name and disposition exists in the system. 
Any outstanding write I/Os which failed will also cause the FCLOSE to fail 
(such I/Os as buffered writes which are done in background). 
Additionally, an illegal disposition (5, 6, or 7) may have been specified. 
This can be detected by FCHECK returning an error of 49. 

SPECIAL CONSIDERATIONS 

Split-stack calls permitted. 

ADDITIONAL DISCUSSION 

"Closing Files", "File Domains", and "Internal Operations for File Accessing" in Section IV. 

For further information on magnetic tape files and associated functions, refer to the MPE File System 
Reference Manual (30000-90236). 
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FCONTROL 

INTRINSIC NUMBER 13 



Performs control operations on a file or device. 

SYNTAX 



IV IV L 

FCQHTRQL(fileman 3 controlcode,poa>am') ; 



The FCONTROL intrinsic performs various control operations on a file or on the device on which the 
file resides . These operations include : 

• Supplying a printer or terminal carriage control directive . 

• Verifying input/output. 

• Reading the hardware status word pertaining to the device on which the file resides . 

• Setting a terminal's time-out interval. 

• Repositioning a file at its beginning. 

• Writing an end -of -file indicator. 

• Skipping forward or backward to a tape mark. 

The FCONTROL intrinsic applies to files on disc, tape, terminal, or line printers. There are some spe- 
cial conditions that exist when FCONTROL is used with files on labeled magnetic tape. Some 
FCONTROL functions cannot be used with labeled tapes , and other functions may produce unexpected 
results . (Refer to controlcodes 5 , 6 , 7 , 8 , and 9 . ) 



PARAMETERS 

fi/Lemon 
controloode 



integer by value (required) 

A word supplying the file number of the file for which the control opera- 
tion is to be performed . 

integer by value (required) . 

An integer specifying one of the following operations to be performed : 

General device control . The par am parameter is transmitted to the ap- 
propriate device driver. The value returned is transmitted to the user 
through param . 

1 Line control. A request to send the value specified in param to the 
terminal or line printer driver as a carriage control directive. For non- 
spooled devices only, use line controls provided by FWRITE when direct- 
ing to a disc or a spooled file . 
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2 Complete input /output . This ensures that requested input/output has 
been physically completed. Valid only for buffered files. Posts the 
block being written whether full or not. This control code is ignored 
for message files. 

3 Read hardware status word. This operation returns the status word 
from the device on which the file resides to param. The returned value 
is the status of the device from the previous input/output operation, 
including FDPENof the file. 

4 Set time-out interval. This code indicates that a time-out interval is to 
be applied to input from a file . If input is requested from a file but is 
not received in this interval, the FREAD request terminates prematurely 
with CCL. The interval itself is specified, in seconds, in a word on the 
user's stack, indicated by param. If this interval is zero, any previously 
established interval is cancelled , and no time-out occurs. A controlcode 
4 only affects the next read and is ignored if the addressed file is not 
being read from the terminal. This code may also be applied to an 
Interprocess Communication (IPC) file. In this case, param specifies 
the length of time that a process will wait when reading from an empty 
file or writing to a full one. For IPC files, the time-out will remain 
enabled until it is explicitly cancelled. Refer to the MPE File System 
Reference Manual (30000-90236). 

5 Reposition the file at its beginning. The next record read or written is 
the first record in the file. This code is not valid for files accessed as 
"append-only". Note that on a labeled magnetic tape file, the tape is 
positioned at the beginning of the opened file, and not necessarily at 
the beginning of the volume. 

6 Write end-of-file. This operation is used to denote the end-of-file 
(EOF) on disc or magnetic tape, and is effective only for those devices. 
If applied to a disc file, the operation writes a logical end-of-data in- 
dicator at the point where the file was last accessed. The disc file label 
also is updated and written to disc. For a file residing on unlabeled 
magnetic tape, a tape mark is written at the current position of the 
tape. This controlcode is not allowed for labeled magnetic tape files. 
When applied in Interprocess Communication (IPC), this controlcode, is 
used to verify the state of the file by writing the file label and buffer 
area to disc; this ensures that the message file can survive system 
crashes. No EOF is written . 

7 Space forward to tape mark. This moves a magnetic tape forward until 
a tape mark is encountered. If used on labeled magnetic tapes, the tape 
is positioned at the beginning of user trailer labels, if any. 

8 Space backward to tape mark. On unlabeled tapes, this moves a mag- 
netic tape backward until a tape mark is encountered. If used on 
labeled tapes, the tape is positioned at the beginning of user header 
labels, if any. 

9 Rewind and unload tape. This repositions a magnetic tape file at its 
beginning and places the tape offline. Not allowed for labeled tapes. 
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NOTE 

Control codes and 3 will be rejected for spooled devicefiles. 
Control codes 5 through 9 (magnetic tape control) will be rejec- 
ted for spooled :DATA tapes. Control codes 6 and 9 will be rejec- 
ted for labeled magnetic tape files. All descriptions pertaining 
to magnetic tape are also valid for serial disc. Refer to the dis- 
cussion of magnetic tape files in the MPE File System Reference 
Manual (30000-90236) for special considerations not covered 
here. 

The following values for controlcode are used in changing terminal charac- 
teristics. Included with the definition of the code is an indication, where 
applicable, of whether the characteristic is reset in BREAK mode or after 
FCL0SE. Also listed are the default settings for each : 

10 Change terminal input speed. (Not reset in BREAK mode; not reset 
after FCLDSE.) 

1 1 Change terminal output speed. (Not reset in BREAK mode; not reset 
after FCL0SE.) 

12 Turn echo facility on. (Not reset in BREAK mode; not reset after 
FCL0SE. Default.) 

13 Turn echo facility off. (Not reset in BREAK mode; not reset after 
FCL0SE.) 

1 4 Disable the system BREAK function. (Reset after FCLDSE.) 

15 Enable the system BREAK function. (Reset after FCLOSE. Default.) 

16 Disable the subsystem BREAK function. (Reset in BREAK mode; 
reset after FCLOSE. Default.) 

17 Enable the subsystem BREAK function. (Reset in BREAK mode; 
reset after FCLOSE.) 

18 Disable tape option. (Default.) 

1 9 Enable tape option . 

20 Disable the terminal input timer. (Reset in BREAK mode ; reset after 
FCLOSE. Default.) 

21 Enable the terminal input timer. (Reset in BREAK mode ; reset after 
FCLOSE.) 

22 Read the terminal input timer. 

23 Disable parity checking. (Default.) 

24 Enable parity checking. 

25 Define line termination characters for terminal input. 
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26 Disable binary transfers. (Default.) 

27 Enable binary transfers. 

28 Disable user block mode transfers. (Not reset in BREAK mode; not 
reset after FCLDSE. Default.) 

29 Enable user block mode transfers. (Not reset in BREAK mode; not 
reset after FCLOSE. ) 

34 Enable line deletion echo suppression. (Not reset in BREAK mode; 
reset after FCLDSE. Default.) 

35 Disable line deletion echo suppression. (Not reset in BREAK mode; 
reset after FCLDSE.) 

36 Set parity. 

37 Allocate a terminal. 

38 Set terminal type. 

39 Obtain terminal type information. 

40 Obtain terminal output speed. 

41 Set unedited terminal mode. 

43 Aborts pending NO WAIT I/O request. For Interprocess Communica- 
tion, CCG is returned when an outstanding I/O operation has com- 
pleted. An IOWA IT call must be issued to finish the request. 

45 Enable/disable extended wait. For Interprocess Communication, a 
value of 1 for par am enables extended wait. This permits a reader to 
wait on an empty file that is not currently opened by any writer , or a 
writer to wait on a full file that has no reader. This will remain in 
effect until an FCDNTROL call with a controlcode of 45 and a par am 
value of is issued. Disabled extended wait, param value of 0, 
specifies that if a second FREAD call is issued and it encounters an 
empty file that has no reader, it will return an end-of-file condition. 

Default: 0. 

46 Enable/disable reading writer's ID. For Interprocess Communication, 
a value of 1 for param enables reading the writer's ID. Each record 
read will have a two -word header. The first word will indicate the 
type of record with the following codes : 

Data record . 

1 Open record . 

2 Close record . 
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The second word will contain the writer's ID number. If the record is 
a data record, the data will follow the header; open and close records 
contain no more information. If the value of par am is 0, reading the 
writer's ID is disabled. Only data is read to the reader's target area. 
The open and close records are skipped and deleted by the file system 
when they come to the head of the message queue, and the two-word 
header is transparent to the reader. 

Default: 0. 

47 Nondestructive read. If the value of param is 1 the next FREADby this 
reader will not delete the record. Subsequent FREAD calls will be unaf- 
fected. When is specified for param the next FREAD by this reader 
will delete the record. 

Default: 0. 

48 Enable/disable software interrupts. The external label (plabel) is con- 
tained in param of your interrupt procedure. In SPL it is passed as a 
parameter by placing an "@" before the procedure name. If the value 
of param is 0, the interrupt mechanism is disabled for this file. 

param logical (required) 

If controlcode is 1 , param denotes a word containing the value to be trans- 
mitted to the terminal or line printer driver as a carriage control or mode- 
control directive. The carriage control directive is selected from the listing 
in Table 2-5, located in the description of the FWR I TE intrinsic. 

The mode -control directive determines whether any carriage control direc- 
tive transmitted through the FWR I TE intrinsic takes effect before printing 
(pre-space movement) or after printing (post-space movement). The 
mode -control directive is selected from octal codes %400or %401 listed in 
Table 2-5, located in the description of the FWR I TE intrinsic. 

If param contains a mode-control directive, then a value is returned to 
param that shows the mode setting of the device as it was before the call to 
FCDNTRDL, as follows: 

Post -spacing. 

1 Pre -spacing. 

If controlcode is 4, param denotes a word in the user's stack that contains 
the time-out interval, in seconds, to be applied to input from the terminal. 

If controlcode is 2, 5, 6, 7, 8, or 9, param is any variable or word iden- 
tifier. This parameter is needed by FCONTRQL to satisfy the internal 
requirements of the intrinsic. It serves no other purpose, however, and is 
not modified by the intrinsic. 



2-72 



CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic . 

CCL Request denied because an error occurred . 

SPECIAL CONSIDERATIONS 

Split -stack calls permitted. 

ADDITIONAL DISCUSSION 

MPE File System Reference Manual (30000-90236). 
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FDELETE 

NO INTRINSIC NUMBER ASSIGNED 
Deactivates a Relative I/O (RIO) record. 

SYNTAX 



0-V IV DV 

FDELETE ifilenvm y recnvm^ ; 



FDELETE deactivates a specified logical record. If no record is specified (or the recnum is negative), 
the next logical record becomes inactive . If the selected record has already been deactivated , CCE is 
returned. The condition can be detected by calling the FCHECK intrinsic; an " INACTIVE RECORD" 
error indicates that the record selected for this FDELETE was already inactive. 

PARAMETERS 

fileman integer by value (required) 

The file number of the file to be deactivated. 

recnum double by value (optional) 

A double integer representing the relative logical record to be modified . 

CONDITION CODES 

CCE Request granted. No error (although inactive record may have been 

encountered). 

CCG Request denied. End -of -file. 

CCL Request denied . Access error. 

SPECIAL CONSIDERATIONS 

Split -stack calls permitted. 
Not applicable to message files . 

ADDITIONAL DISCUSSION 

MPE File System Reference Manual (30000-90236). 
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FDEVICECONTROL 

NO INTRINSIC NUMBER ASSIGNED 



Provides control operations to a printer, Workstation Configurator, (version G.01.00 or later) or a 
spooled devicefile. 

SYNTAX 



IV LA IV IV 

FDEVI CECDNTRQL (.filertt4m,taj^et 9 tccamt a cantrolcode , 

LV LV I 

paraml ,param2 >ermum} \ 



FDEVICECONTROL may be used to download character sets, forms, and internal or control tables used 
in printing. It may also be used to control the page size, pen positioning, use of character sets and 
form , and the number of copies of each page to be printed , and other characteristics of the printing 
environment. The IFS/3000 intrinsics (which perform the same functions for the HP 26 8x as 
FDEVICECONTROL), together with the layout of the Character Set Load Record and Form Set Load 
Record and the Logical Page Table, are discussed in the IFS/3000 Manual (36580-90001). 



PARAMETERS 

filenum 

target 
tcount 



controlcode 



integer by value (required) 

A word supplying the file number of the devicefile. This value is obtained 

from FOPEN. 

logical array (required) 

This array contains data to be passed to the device . In general , it contains 

character sets, forms, or Vertical Format Control (VFC) information. 

integer by value (required) 

An integer indicating the length of target, the units of which are deter- 
mined by the sign. A positive value indicates the specified length is words; 
a negative value indicates bytes. 

integer by value (required) 

The code number of the operation to be performed. These are described 

below . 

128 - Character Set Selection. 



paraml (8:8) 
param2 (8:8) 



Primary character set identification. 
Secondary character set identification. 



The HP 26 8x page printer can contain up to 32 character sets, thus allow- 
ing the use of a variety of fonts, styles, print rotations, and languages. 
Use controlcode 1 34 to download character sets to the printer. Use control- 
code 128 to select any two downloaded character sets to be the current 
primary and secondary character sets. 
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To change to the secondary character set a character at a time, set the 
eighth bit of the byte coding for the desired ASCII character. The HP 26 8x 
will strip out this bit and print, in the secondary character set, the charac- 
ter represented by the remaining 7 -bit value. To change to the secondary 

character set for a number of characters and over several lines, insert a 

c c 

shift-in character (N ) in the data. Insert a shift-out character (D ) where 

the primary character set is to be re -activated. 

129 - Logical Page Activation/Deactivation Request. 

paraml (0:1) =0 Ignores the left byte of param.2. 

= 1 Deactivates the Logical Page Table entry iden- 
tified in the left byte of par am 2. 

paraml (1:1) =0 Ignores the right byte of param2. 

= 1 Activates the Logical Page Table entry identified 
in the right byte of par am 2. 

param2 (0:8) Logical Page Table entry (from to 31) to be deac- 

tivated. Ignored if paraml (0:1 )=0. 

par am 2 (8:8) Logical Page Table entry (from to 31) to be ac- 

tivated. Ignored if paraml (1 : 1 )=0. 

This controlcode allows you to cancel or enable the printing of logical pages 
during a job through the activation or deactivation of those pages. 

Every physical page is composed of one or more logical pages. When the 
HP 26 8x begins to print each physical page, it scans the Logical Page Table 
(LPT) for the first logical page labeled as active. The printer then con- 
tinues searching the table sequentially for active pages and printing them 
until it has printed the last active page. At this point the HP 26 8x per- 
forms a physical page eject and starts the sequence again. There must be at 
least one active LPT entry while the HP 26 8x is printing. 

1 30 - Relative Pen Displacement. 

paraml A 16 -bit signed integer containing the desired X axis 

displacement, in dots, of the pen from its current 
position. 

param2 A 16-bit signed integer containing the desired Y axis 

displacement, in dots, of the pen from its current 
position. 

No pen movement will result from requests to move the pen off the logical 
page. As the coordinate system is based upon the current logical page itself 
and not upon the page's orientation with respect to the printer, you need 
not consider how the page has been rotated when assigning displacement 
values to paraml and param2. Since the dot density for the HP 2680 (180 
dots per inch) differs from that for the HP 2688 (300 dots per inch), the 
effects of paraml and param2 will be different. 
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1 3 1 - Absolute Pen Move. 
paraml 



param2 



An integer containing the X coordinate, in dots, of 
the point to which you wish to move the pen. 

An integer containing the Y coordinate, in dots, of 
the point to which you wish to move the pen. 



The values in paraml and param2 are measured from the upper left corner 
of the logical page. As with controlcode 1 30, you need not take page rota- 
tion into account when assigning coordinates , and the printer will not move 
the pen if the location you specify is off the logical page. Since the dot 
density for the HP 2680 (180 dots per inch) differs from that for the HP 
2688 (300 dots per inch), the effect of paraml and param2 will be 
different. 

132 - Define Job Characteristics. 



paraml (0:1) 



paraml (1 :1) 



param2 



=0 This bit is ignored. 

= 1 The printer will not print job separation marks 
until the next job is open . 

=0 This bit is ignored. 

= 1 Par am 2 contains the maximum allowable num- 
ber of copies of each page . 

Significant only if paraml (1:1)=1. This specifies 
the maximum number of copies the printer will 
make of any one page for the current job. The 
default maximum is 32,767. 



1 3 3 - Define Physical Page . 

The following bits are ignored if set to zero: 



paraml (0:1) 
par am 1 (1:1) 
paraml (2:1) 
paraml (3:1) 
paraml (4:1) 
paraml (5:1) 
paraml (6:1) 
paraml (7:1) 



*1 Turn on multicopy form overlay feature. 

= 1 Turn off multicopy form overlay feature. 

= 1 Reserved. 

= 1 Redefine the physical page length. 

= 1 Redefine the number of copies per page desired. 

= 1 Reserved. 

= 1 Reserved. 

= 1 Reserved . 
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paraml (8:8) New physical page length in units of 0.25 inches. 

The length may not be less than 3.0 inches (a value 
of 12) or greater than 17.0 inches (a value of 6 8). 

param2 Contains the number of copies of each page you 

want to print. If this number exceeds the maximum 
defined in paraml of controlcode 132, only the max- 
imum number of copies is printed . 

Although FDEVICECDNTRDL will accept page length values that are multi- 
ples of 0.25 inches, the HP 26 8x printer is able to produce only pages that 
are x multiples of 0.5 inches. For this reason, only use even values in 
paraml (8:8). In other words , bit (15:1 )=0. 

1 34 - Download/Delete Character Set. 

paraml (0:1) =0 Download the character set identified in the 

right-hand byte of param2 into the HP 26 8x. 

= 1 Purge the character set identified in the right- 
hand byte of param2 from the HP 26 8x. 



param2 (0:1) 



param2 (8:8) 



=0 Indicates the first record of a load. 

= 1 Indicates a continuation of the previous record. 

Character set identifier - an integer from to 31. 



If you attempt to download a character set having the same identifier as 
one existing in the printer, then the HP 26 8x will purge the existing 
character set and repack the user area before loading the new font. 
However, before the modification of the user area, the HP 26 8x prints all 
data currently in its buffer, as it does whenever you load, overlay, or 
delete a character set, form, or Vertical Format Control set (VFC). 

1 3 5 - Download/Delete Form . 

paraml (0:1) =0 Load the form set identified in the right-hand 

byte of param2. 

= 1 Purge the identified form set from the HP 268x 
printer's memory . 

param2 (0:1) =0 Indicates the first record of a load. 

= 1 Indicates a continuation of the previous record. 

param2 (8:8) Form set identifier - an integer from to 31. 
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If you attempt to download a form set having the same identifier as one ex- 
isting in the printer, then the HP 26 8x will purge the existing form set and 
repack the user area before loading the new form. However, before the 
modification of the user area, the HP 26 8x prints all data currently in its 
buffer, as it does whenever you load, overlay, or delete a character set, 
form, or Vertical Format Control set (VFC). 

136 - Download Logical Page Table. 

param 1 Is not used . 

param2 (0:1) =0 Indicates the first record of a load. 

= 1 Indicates a continuation of the previous record . 

A logical page is a page of data that may or may not take up an entire sheet 
of paper. It is possible to print up to eight logical pages on one physical 
page. The Logical Page Table, 513 words long, contains some of the in- 
formation needed to print up to 32 logical pages, so that the set of up to 
eight logical pages printed on any one physical page may be varied. 

1 3 7 - Download Multicopy Form Overlay Table . 

param 1 Is not used . 

param 2 Is not used. 

This operation allows you to emulate a multipart carbon by printing up to 
eight copies of a page, each on one or two different forms. 
FDEVICECONTROL downloads a table containing one word of information 
for each of the eight possible copies to be overlaid with a form into the 
printer's memory . The format of each word of the table is : 

Bit (0:1) =0 This bit is ignored. 

= 1 Form 1 is to be overlaid on the physical page . 
(1:1) =0 This bit is ignored. 

= 1 Form2 is to be overlaid on the physical page. 
(2:4) Reserved. 

(6:5) Forml identifier - an integer from to 31 . 

(11:5) Form 2 identifier - an integer from to 31 . 
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1 38 - Download/Delete Vertical Format Control (VFC). 
paraml (0:1) =0 Load a VFC. 

= 1 Delete a VFC. 

paraml (0:1) =0 This is the first record of a load. 

= 1 This record is logically a continuation of the 
previous record . 

param2 (8:8) VFC set identifier - an integer from to 31. 

The Vertical Format Control table is an ASCII file downloaded to the HP 
26 8x printer in order to give specific instructions on the print density, 
location of the top of the page, the bottom of the page, and other 
specifications of the printed page. 

The HP 26 8x expresses the height of a printed line in dots and the system 
uses this value to compute line positions on the page. Because these space 
measurements are relative to the top of the logical page , as opposed to the 
physical page, you may use the same or different Vertical Format Control 
tables for logical pages of different rotations. 

139 - Download/Delete a Picture. 
paraml (0:1) =0 Load a picture. 

■ 1 Delete a picture . 

param2 (0:1) =0 This is the first record of a load. 

= 1 This record is a logical continuation of the 
previous record . 

param2 (8:8) Picture identifier - an integer from to 31 . 

When the picture is downloaded to the HP 26 8x, it changes every pointer 
to reflect where the dot per bit symbol actually is in memory. If a picture 
is downloaded and one is already present with the same identifier (0-31), 
then the original one is overwritten in the Picture Descriptor Block (PDB). 
The area taken up by the deleted picture will be freed as soon as the page 
has been transferred to paper. 
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140 - Page Control. 

par ami (15:1) =0 Do not eject a physical page. 



paraml (13:2) 



param2 (8:8) 



= 1 Do a physical page eject before going to the 
specified logical page. This bit has no effect if 
this is the first record since an environment load , 
FOPENor FCLOSE. 

Auto eject mode. 

=00 Use auto eject flag of last data record (default 
at start of job is auto eject enabled). 

=01 Enable auto eject (select VFC channel 1 on 
new page) . 

= 1 1 Disable auto eject (position pen at top of page). 

Logical page number - an integer from to 31. 



The logical page identified in par am 2 becomes the current logical page even 
if other logical pages have entries which precede it in the Logical Page 
Table. FDEVICECONTRQL activates the specified page if it is inactive, and 
the HP 26 8x performs a physical page eject if paraml (1 5 : 1 )=1 . 

141- Clear Environment. When set to zero, the following bits are ignored. 

paraml (0:1) =1 Clear all character sets. 

par am 7(1:1) =1 Clear all forms . 

paraml (2:1) =1 Clear all Vertical Format Controls (VFCs). 

par am 7(3:1) =1 Clear all pictures . 

param2 Is not used. 

The printer will flush all data currently in its buffers, and then perform 
the indicated clears, if any. 

142 - Reserved. 

143 - Load the Default Environment. 

paraml Is not used. 

par am 2 Is not used. 

The HP 26 8x printer flushes all data, erases the user area, and loads the 
default character set, the Vertical Format Control (VFC), and the Logical 
Page Table (LPT). 
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144 - Print Picture. 
par ami (0:1) 

paraml (1:1) 

par ami (2:14) 
param2 (0:1) 

param2 (1:1) 
param2 (2:14) 



=0 Temporary picture. 

= 1 Addressable picture. 

=0 X and Y are relative to the current pen position. 

= 1 X and Y are absolute pen position to the logical 
page. 

X coordinate for picture placement (radixed 
integer) . 

=0 First of temporary picture load. 

= 1 Continuation record for load . 

Is not used. 

Y coordinate for picture placement (radixed 
integer). 



The X and Y values are radixed integers expressed in the coordinate system 
of the logical page. The paraml values allow the specification of picture 
location relative to the current position of the logical pen or at an absolute 
location on the logical page. In either case, the position refers to the user- 
selected location on the picture specified in the Picture Descriptor Block 
(PDB) as downloaded by the host. No bounds checking is done for pictures. 

145 -End of Job. 

paraml Is not used. 

par am 2 Is not used. 

1 46 - Device Extended Capability Mode. 
paraml =0 Clear. 

= 1 Set. 
par am 2 Is not used. 
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parand, param2 



errnum 



192 - Access Workstation Configurator terminal configuration file. 

paraml Item number of function. Refer to the Workstation 

Configurator Reference Manual (30239-90001) for 
values . 



par am 2 



Access code 

1= Return current value in target . 

2= Set item to value in target . 

3= Set item to value in target, and return current 
value in target . 



193 -Record processing information for NRJE spoolfiles. 



par am 1 



param2 (14:1) 



param2 (15:1) 



Integer indicating the character code (e.g. ASCII) of 
spoolfile data. Refer to SNA NRJE Network 
Remote Job Entry User/Programmer Reference 
Manual (30245-90001). 

: Data is not compacted . 

1 : Data is compacted . 

: Data is not compressed . 

1 : Data is compressed . 



logical by value (required) 

For each value of controlcode , there may be several possible values for 
paraml and param2, which define the operation in more detail. These are 
described in the list of operation code numbers under controlcode . 

integer (required) 

If no error occurs errnum is set to zero. If an error occurs errnum contains 
the File System error code. If FDEV I (DECONTROL detects a bounds violation 
for errnum (i.e. an address outside the user's stack area), errnum is 
unchanged . 



CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied because an error occurred. 

ADDITIONAL DISCUSSION 

IFS/3000 Reference Guide (36580-90001). 

Point-to-Point Workstation I/O Reference Manual (30000-90250). 
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FERRMSG 

INTRINSIC NUMBER 305 

Returns message corresponding to FCHECK error number. 

SYNTAX 



I LA I 

FERRMSG Cerrorcode ,msgbuf ,msglgth ) ; 



The FERRMSG intrinsic returns a message to msgbuf that corresponds to an FCHECK error number. 
This makes it possible to display an error message from your program. The message describes the error 
associated with the error number provided in the errorcode parameter . 

PARAMETERS 

eiTOPCode integer (required} 

An integer indicating the error code for which a message is to be returned. 
It should contain an error number returned by FCHECK. 

msgbuf logical array (required) 

A logical array to which the message associated with errorcode is returned 
by FERRMSG. In order to contain the longest string, msgbuf must be a min- 
imum of 72 characters long. 

msglgth integer (required) 

An integer to which the length of the msgbuf string is returned. The 
length is returned as a positive byte count. 

CONDITION CODES 

CCE Request granted. 

CCG Request not granted because no error message exists for this errorcode. 

CCL Request not granted. The msgbuf address may be out of bounds, msgbuf 

may not be large enough, or msglgth is out of bounds. 

ADDITIONAL DISCUSSION 

"Using FERRMSG" in Section IV. 



2-84 



FFILEINFO 

NO INTRINSIC NUMBER ASSIGNED 



Provides access to file information. 

SYNTAX 



0-V IV IV BA 

FF I LE I NFQ (filenum [ , itemnuml , itemoaluel ] 

[ ,itemnnm2 , item0alue2 ] 
[ y-itemnvmZ iitemoaltieZ ] 
[ ,itemnum4 ,itemi)alue4 1 
[ , itemnumS , iteiwalue5 1 ) ; 



The itemnum/itemvalue parameters must appear in pairs. Up to five items of information can be 
retrieved by specifying one or more itemnum/itemvalue pairs. FFILEINFO is designed to allow for fu- 
ture changes so that new file information can be defined and accessed. 



PARAMETERS 

fileman 

itemnum 
itemoalue 



integer by value (required) 

MPE file number returned by FOPEN. 

integer by value (optional) 

Cardinal number of the item desired; this specifies which item value is to 

be returned. (Refer to "Item#" in Table 2-3.) 

byte array (optional) 

Returns the value of the item specified by the corresponding itemnum ; the 
data type of the item value depends on the item itself. (Refer to "Item 
Value" in Table 2-3.) 



CONDITION CODES 

CCE No error. 



CCG 
CCL 



Not used. 

Access or calling sequence error. 



ADDITIONAL DISCUSSION 

MPE File System Reference Manual (30000-90236). 
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Table 2-3. Item Values Returned by FFILEINFO 



ITEM* ITEM VALUE 

1 Filename 

2 Foptions 

3 Aoptions 

4 Record 

5 Device type 

6 Ldev ft of remote file 

7 Hdaddr 

8 File code 

9 Record pointer 

10 EOF 

11 File limit 

12 Log count 

13 Physcount 

14 Block size 

15 Extent size 

16 Number of extents 

17 User labels 

18 Creator ID 

19 Label address 

20 Blocking factor 

21 Physical block size 

22 Data block size 

23 Offset to data in blocks 

24 Offset of Active Record Table 

25 Size of Active Record Table 
within the block 

26 Vol. ID(label tape) 

27 Vol. set ID(label tape) 

28 Expiration date(Julian) 

29 File sequence number 

30 Reel number 

31 Sequence type 

32 Creation date(Julian) 

33 Label type 

34 Current* of writers 

35 Currentft of readers 

36 File Allocation Date 

37 File Allocation Date I 

38 SPOOLFILE Devicefile number 

(Bit (0:1) = Input Spoolf 
(0:1) = 1 Output Spool 



TYPE 
BA 

L 

L 

I 

I 

L 

L 

I 

D 

D 

D 

D 

D 

I 

L 

I 

I 

BA 

D 

I 

I 

I 

I 

I 

I 



BA 
BA 



(see 
(see 
(see 
(see 
(see 
(see 
(see 
( see 
(see 
(see 
(see 
(see 
(see 
(see 
(see 
(see 
(see 
(see 
(see 
(see 



FGETINF0) 
FGETINF0) 
FGETINFO) 
FGETINF0) 
FGETINFO) 
FGETINFO) 
FGETINFO) 
FGETINFO) 
FGETINFO) 
FGETINFO) 
FGETINFO) 
FGETINFO) 
FGETINFO) 
FGETINFO) 
FGETINFO) 
FGETINFO) 
FGETINFO) 
FGETINFO) 
FGETINFO) 
FOPEN) 



(RIO files) 



UNITS 



words/bytes 



records 
records 
records 
records/bytes 
sectors 



words 
words 
words 
words 
words 



(CALENDAR format ) 
(CLOCK format) 



le 
ile 



Bits (1:15) 



Devicefile Number) 
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Table 2-3. Item Values Returned by FFILEINFO (Continued) 



ITEM* 


ITEM VALUE TYPE UNITS 


39 


RESERVED 


40 


Disc or diskette device status D 


41 


Device type I 


42 


Device subtype I 


43 


Environment file name BA 


44 


Last disc extent allocated I 


45 


Filename from labeled tape HDR1 record BA 


46 


Tape density I 


47 


DRT number I 


48 


UNIT number I 


49 


Software interrupt PLABEL I 


50 


Real device number of the file I 


51* 


Remote environment number I 


52 


Last modification time (CLOCK format) D 


53 


Last modification date (CALENDAR format )L 


54 


File creation date (CALENDAR format) L 


55 


Last access date (CALENDAR format) L 


56 


# data blocks in a variable length file I 


57 


# of the user label written to the file I 


58 


Number of opens for output I 


59 


Number of opens for input I 


60 


Terminal type, defined as: I 




O-File's associated device is not a terminal 




1-Standard hardwire or multi-point terminal 




2-The terminal is connected via a phone-modem 




3 -DS pseudo terminal 




4-X.25 Packet Switching Netword PAD 




(Packet Assembler Disassembler) terminal 


61** 


NS/3000 remote environment id name 



* If NS/3000 RFA (Remote File Access) is being used specify DSDEVICE ldev# when a DS (point- 
to-point or X.25) link is being used. 

** If NS/3000 RFA is being used: DSDEVICE ldev# in ASCII if a point-to-point link is being used; 
the X.25 node name if an X.25 link is being used. Users of item 61 must provide a buffer for 
the node name (or envid). This buffer must be able to accommodate the required space of 52 
bytes. If not you risk data corruption on variables whose DB-relative location follows that of the 
Item 61 buffer or FSERR 73, "BOUNDS VIOLATION" from FFILEINFO. 
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FGETINFO 

INTRINSIC NUMBER 11 

Requests access and status information about a file. 

SYNTAX 



0-V IV BA L L I 
FGET I NFO (filenum, filename ,f options ,aoptions s recsize , 

I L L I D D D 
devtype , ldnum,ndaddr ,filecode ,recpt ,EOF ^flimit 

D I L I 
logoount yphysooitnt , blksize >extsize ,numextents t 

1 BA D 
userlabels ) creatorid i labaddr') ; 



Once a file is opened on any device, the FGETINFO intrinsic can be used to request access and status 
information about that file. 



PARAMETERS 

filenum 

filename 



foptions 



integer by value (required) 

A word supplying the file number of the file about which information is 

requested . 

byte array (optional) 

A 2 8 -character byte array to which the actual designator of the file being 

referenced is returned , in the format : 

filename . groupname . accountname 

When the actual designator is returned , unused bytes in the array are filled 
with blanks on the right. A nameless file will return an empty string. 

Default: The actual designator is not returned. 

logical (optional) 

The foptions parameter returns seven different file characteristics by set- 
ting corresponding bit groupings in a 16 -bit word. Correspondence is from 
right to left. The file characteristics returned (the bit settings are sum- 
marized in Figure 2- 1 ) are as follows: 

Bits (14:2) - Domain f opt ion. 

The file domain that was searched by MPE to locate the file, indicated by 

these bit settings : 

=00 The file is a new file . 

=01 The file is an old permanent file. 

= 10 The file is an old temporary file. 

= 1 1 The file is an old file . 
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Bit (1 3: 1) - ASCII/binary f option. 

=0 Binary. 

= 1 ASCII. 

Bit (10:3) - Default file designator f option. 

=000 The actual file designator is the same as the formal file designator. 

=001 The actual file designator is SSTDLIST. 

=010 The actual file designator is $NEWPASS. 

=01 1 The actual file designator is $0LDPASS. 

= 100 The actual file designator is $STDI N. 

= 101 The actual file designator is $STDI NX. 

= 110 The actual file designator is SNULL. 

Bits (8:2) - Record format f option. 

The format in which the records in the file are recorded , indicated by these 

bit settings : 

=00 Fixed-length records. 

=01 Variable-length records. 

= 1 Undefined -length records . 

= 11 Spoolfile. 

Bit (7:1) - Carriage control f option. 

=0 No carriage -control character expected. 

= 1 Carriage-control character expected . 

Bit (6 : 1 ) - MPE tape label f option. 

=0 Nonlabeled tape. 

= 1 Labeled tape. 

Bit (5:1) - Disallow : F I LE equation f option . 

This option ignores any corresponding :FILE command, so that the 
specifications in the FOPEN call take effect (unless overridden by those in 
the file label) . The following bit settings apply : 

= 1 Disallow : FILE command. 

=0 Allow : FILE command. 
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Bits (2:3)- File type f option. 

=000 Ordinary file. 

=001 KS AM file. 

=010 Relative I/O file. 

= 100 Circular file (discussed in Section III). 

= 110 Message file. 

Bits (0:2) - Reserved for MPE. Should be set to zero. 

Default : Foptions are not returned . 

aoptions logical (optional) 

The aoptions parameter returns up to seven different access options 
represented by bit groupings in a 16 -bit word, as described below. The bit 
settings are summarized in Figure 2-2. 

Bits (12:4) - Access type aoptions. 

The type of access allowed users of this file follows : 

=0000 Read access only . 

=0001 Write access only . 

=0010 Write access only, but previous data in file is not deleted. 

=00 1 1 Append access only. 

=0100 Input /output access . 

=0101 Update access . 

=0110 Execute access . 

Bit (11:1) - Multirecord aoption . 

=0 Select nonmultirecord mode. 

■ 1 Select multirecord mode . 

Bit (10:1) - Dynamic locking aoption . The bit settings are : 

=0 Disallow dynamic locking/unlocking. 

= 1 Allow dynamic locking/unlocking . 



2-90 



Bits (8:2) - Exclusive aoption. 

This aoption specifies whether a user has continuous exclusive access to this 

file, from the time it is opened to the time it is closed. The bit settings 

are: 

=00 Default. 

=01 Exclusive access. 

= 1 Semi -exclusive access . 

= 11 Shared access. 

Bit (7:1) - Inhibit buffering aoption. 

This option inhibits automatic buffering by MPE and allows input/output 
to take place directly between the user's stack or extra data segment and 
the applicable hardware device. 

=0 Normal buffering. 

= 1 Inhibit buffering. 

Bit (5:2) - Multiaccess mode aoption. 

This field provides the accessor with the means of sharing access to the file. 

=00 Nonmultiaccess. 

=01 Multiaccess. 

■ 1 Inter - job multiaccess . 

Bit (4:1) - NO WAIT I/O aoption. 

This bit allows the accessor to initiate an I/O request and to have control 

returned before the completion of the I/O. 

=0 NO WAIT I/O not in effect. 

= 1 NOW AIT I/O in effect. 

Bits (3:1) - File Copy Access aoption. 

=0 Access in file's native mode. 

= 1 Access as standard sequential file. 

Bits (0:3) Reserved for MPE. 

Default: Aoptions are not returned. 

reesize integer (optional) 

A word to which the logical record size associated with the file is returned. 
If the file was created as a binary type, this value is positive and expresses 
the size in words. If the file was created as ASCII type, this value is nega- 
tive and expresses the size in bytes. 
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For Interprocess Communication (IPC) when a call to FCQNTRDL with a 
controlcode of 46 ("FCONTROL 46") is in effect, the value returned in rec- 
size will be the size of the user's data records, including the two -word 
header. 



devtype 



Default : The logical record size is not returned . 

integer (optional) 

A word to which the type and subtype of the device being used for the file 
is returned, where bits (0:8) indicate device subtype, and bits (8:8) indi- 
cate device type. If the file is not spooled, which can be determined from 
hdaddr (0:8), the returned devtype is actual. The same is true if the file is 
spooled and was opened via the logical device number. However, if an 
output file is spooled and was opened by device class name, devtype con- 
tains the type and subtype of the first device in its class, which may be dif- 
ferent from the device actually used. If you have opened a device in a 
serial disc class, the type returned in bits (8:8) is 31 (%37) even though the 
real device type is as specified in Table 4-2, Classification of Devices, in 
the MPE V System Operation and Resource Management Reference Manual 
(32033-90005). Device type 7 (%07) is returned by FGETINFD for devices 
opened in a foreign disc class. 



Idnum 



Default: The device type and subtype are not returned. 

logical (optional) 

A word to which the logical device number (Idev) associated with the device 

on which the file resides is returned. 



hdaddr 



If the file is a disc file, the logical device number will be that of the first 
extent. If the file is spooled, Idnum will be a virtual device number which 
does not correspond to the system configuration I/O device list. If the file 
is located on a remote computer, linked by a DS (point-to-point or X.25) 
link, the left eight bits (0:8) are the logical device number of the 
Distributed System (DS) device. If the remote computer is linked by 
NS/3000, the left eight bits are the remote environment of the connection. 
The right eight bits (8:8) are the logical device number of the file on the 
remote computer. For version G. 00. 00 or later, note that if Idev is greater 
than 255, is returned. For version G.02.00 or later, if either the DS 
device for the RFA or the Idev is 0, then the entire word is 0. 

Default : The logical device number is not returned . 

logical (optional) 

A word to which the hardware address of the device is returned , where bits 
(0:8) are the Device Reference Table (DRT) number, and bits (8:8) are 
the unit number. The limitations for the Device Reference Table number 
are discussed in "Special Considerations". If the device is spooled, the DRT 
number will be zero and the unit number is undefined. 



filecode 



Default : The hardware address is not returned . 

integer (optional) 

A word to which a disc file's file code is returned. 



Default: The file code is not returned. 
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recpt 



EOF 



flimit 



double (optional) 

A double-word to which a double integer representing the current logical 
record pointer setting is returned. This is the displacement in logical 
records from record number in the file. It identifies the record that 
would next be accessed by an FREADor FWRITEcall. 

Default: The logical record pointer setting is not returned. 

double (optional) 

A double-word to which a double positive integer equal to the number of 
logical records currently in the file is returned. If the file does not reside 
on disc, this value will be zero. For Interprocess Communication (IPC) 
when a call to FCDNTROL with a controlcode of 46 is in effect, the number 
of records returned in EOF will include open, close, and data records. 

Default: The number of logical records in the file is not returned. 

double (optional) 

A double -word to which a double positive integer representing the number 
of the last logical record that could ever exist in the file, because of the 
physical limits of the file is returned. If the file does not reside on disc, 
this value will be zero. 



logoount 



physcount 



blksize 



extsize 



Default: The logical record count is not returned. 

double (optional) 

A double-word to which a double positive integer representing the total 
number of logical records passed to and from the user during the current 
access of the file is returned. 

Default : The logical record count is not returned. 

double (optional) 

A double-word to which a double positive integer is returned. This value 
represents the total number of physical input/output operations performed 
within this process against the file since the last FDPEN call. 

Default: The number of I/O operations is not returned. 

integer (optional) 

A word to which the block size associated with the file is returned. If the 
file is a binary file, this value is positive and expresses the size in words. If 
the file is ASCII, this value is negative and shows the size in bytes. 

Default : The block size is not returned . 

logical (optional) 

A word to which the disc extent size associated with the file (in sectors) is 

returned. 

Default: The disc extent size is not returned. 
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numextent 



userlabels 



creatorid 



labaddv 



integer (optional) 

A word to which the maximum number of disc extents allowable for the 

file is returned . 

Default: The maximum allowable number of extents is not returned. 

integer (optional) 

A word to which the number of user header labels defined for the file when 
it was created is returned. If the file is not a disc file, this number is zero. 
When an old file is opened for overwrite output , the value of userlabels is 
not reset and old user labels are not destroyed . 

Default: The number of user labels is not returned. 

byte array (optional) 

A byte array to which the eight-byte name of the user who created the file 

is returned. If the file is not a disc file, blanks are returned. 

Default : The user name is not returned . 

double (optional) 

A double -word to which the sector address of the file label is returned. 

The high -order eight bits show the logical device number. The remaining 

24 bits show the absolute disc address. If the file is not a disc, zero is 

returned. 

Default: The sector address is not returned. 



CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied because an error occurred . 

ADDITIONAL DISCUSSION 

MPE File System Reference Manual (30000-90236). 
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BITS 


(0:3 


(23) 


(BcD 


<ftO 


CM) 


(6:2) 


(IfcS) 


flafl 


(142* 


FIELD 


(RE- 


FILE 


DISALLOW 


MPE 


CAR- 


RECORD 


DEFAULT 


ASCII 


DOMAIN 




SERVED) 


TYPE 


:FILE 


TAPE 
LABELS 


RIAGE 
CONTROL 


FORMAT 


FILE 
DESIGNATOR 


BINARY 




MEANING 




00 


0=STD 


0=Alk)w 


0=Non- 


0=NOCCTL 


00=Fixed 


000=FIUENAME 


0=BINARY 


OOMtewFlo 






00 
01 
10 

11 


1=KSAM 
0=RIO 
0=OR 
0=MSG 


:FILE 

1=No 
:FIUE 


Labeled 
Tape 

1=Labled 
Tape 


1=CCTL 


01=Variabte 

tt=Un- 

deftied 

11=Spoolfile 


001=$STDUST 
010=$NEWPASS 

011=$OLDPASS 
100=$STDIN 
101=$STD1NX 
110=$NULL 


1=A5CII 


01=OW 

Permanent 
File 

KKM 
Temporary 
File 

11=OW 

Permanent Or 
Temporary 
File 



NOTE: Double lines indicate octal digit boundaries. 

Figure 2-1 . Foptions Bit Summary 



BITS 


«*S) 


(3D 


(44 


(&2) 


0* 


(8:2) 


flttt 


flirt 


(124) 


FIELD 


(RE- 
SERVED) 


FILE 

COPY 

ACCESS 


NOWAIT 
l/O 


MULTI- 
ACCESS 


INHIBIT 
BUF- 
FERING 


EXCLU- 
SIVE 
ACCESS 


DYNAMIC 
LOCKING 


MULTI- 
RECORD 
ACCESS 


ACCESS 
TYPE 


MEANING 




0=Acce88 
Native 


1=NOWAIT 


00=Non 
Multi- 


0=BUF 


00=0efault 


0=No FLOCK 
Akwed 


0=NoMulti- 
Record 


000=fiead 
Only 






Mode 


0=Non- 
NOWAIT 


Access 


1=NOBUF 


01=Exdusive 


1=FLOCK 


1=Multi- C 


001=Write 






1=?Acoess 
As Stand- 
ard Se- 
quential 
Fie 




OlOnly 
htra- 
JobMJtl- 
Access 

«=tater- 
Job 
Multi- 
Access 
Allowed 




10=Serni- 
exdusive 
Access 
Read 

11=Share 


Alowsd 


Record 

C 

C 
( 

( 

< 


Only 

0tO=Writ» 
(Save) 
Only 

) OltaAppend 
Only 

) 100 Read/ 
Vfrite 

] 101=Update 

) 110=Execut« 



NOTE: Double lines indicate octal digit boundaries. 



Figure 2-2. Aoptions Bit Summary 
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FINDJCW 

INTRINSIC NUMBER 86 

Searches the Job Control Word Table for a specified Job Control Word (JCW). 

SYNTAX 



BA L I 

F I ND JCWCjctfname, jciwalne , status ) ; 



PARAMETERS 

jcumame 

jcaodlue 
status 



byte array (required) 

A byte array containing the name of the Job Control Word (JCW) to be 
found. May contain up to 2 5 5 alphanumeric characters, starting with a 
letter and ending with a nonalphanumeric character such as a blank. 

logical (required) 

A word to which the value of jcwname is returned, if jcwname is found. If 

jcwname is not found, jcwvalue is unchanged. 

integer (required) 

A word to which a value denoting the execution status of the intrinsic is 
returned, as follows: 

Successful execution, jcwname found. 

1 Error, jcwname greater than 255 characters long. 

2 Error , jcwname does not start with a letter. 

3 Error, jcwname not found in JCW table. 

4 Error, attempted to assign a value to an MPE -defined JCW value 
mnemonic (OK, WARN, FATAL, or SYSTEM). 

5 Error , cannot assign a value to a system -reserved JCW. 

Value 5 will only be returned if the fundamental operating software is ver- 
sion G. 00. 00 or later. 



SPECIAL CONSIDERATIONS 

There are three types of JCWs in the system: user-defined JCWs, system -defined JCWs, and system- 
reserved JCWs. FINDJCW can return the value of any type of JCW. The system -reserved JCWs are 
HPDATE, HPDAY, HPHDUR, HPMINUTE, HPMDNTH, and HPYEAR. 
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CONDITION CODES 

The condition code remains unchanged . 

ADDITIONAL DISCUSSION 

"Interprocess Communication" in Section V. 
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FINTEXIT 

INTRINSIC NUMBER 23 

Causes the return from a user's interrupt procedure. (Available only on version G. 01 .00 or later.) 

SYNTAX 



0-V LV 

FINTEXITCin^state); 



The FINTEXIT intrinsic is used to cause the return from the user's interrupt procedure. On the 
return, software interrupts are set according to int state. If int state is omitted, the software interrupts 
are enabled by default . 

PARAMETERS 

intstate logical by value (optional) 

A logical value indicating the state in which software interrupts should be 
left. Bit (15:1) controls this as follows : 

= 1 Enable software interrupts. 

=0 Leave software interrupts disabled. 

Default: (15:1)=1. 

CONDITION CODES 

The condition code remains unchanged . 

ADDITIONAL DISCUSSION 

MPE File System Reference Manual (30000-90236). 
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FINTSTATE 

INTRINSIC NUMBER 24 

Enables/disables all software interrupts against the calling process. (Available only on version 
G.01.00 or later.) 

SYNTAX 



L LV 

oldstate : =F INTSTATECin*s*erte) ; 



The software interrupt facility enables users to perform FREAD/FWRITE completion processing with 
their own interrupt procedure. An FREAD/FWRITE call is necessary to initiate the I/O request. Both 
of these intrinsics return to the user's process as soon as the request has been started. When the opera- 
tion completes, the user's program is trapped (or "interrupted") and goes to a user chosen interrupt 
procedure. This performs whatever processing is necessary and then resumes the user's original 
program. 

Soft interrupts are "armed" for a particular file by specifying the interrupt procedure's plabel in an 
FCDNTROL call with a controlcode of 48. Calling "FCONTROL 48" with a parameter of will disarm 
the software interrupt mechanism . 



NOTE 



MPE inhibits software interrupts just before entering an 
interrupt procedure. This is done to stop unwanted nest- 
ing of the interrupt procedures. Each interrupt proce- 
dure should call FINTEXIT (Refer to FINTEXITin this 
section) to re-enable other interrupts just before it exits. 

Software interrupts are normally automatically in- 
hibited before a Y c trap procedure. The trap procedure 
may elect to allow software interrupts, however, by 
calling the FINTSTATE intrinsic. The RESETCDNTROL 
intrinsic will restore the interrupt state of the process to 
its pre-Y c value (unless the trap procedure issues an 
FINTSTATE call, in which case RESETCDNTROL makes 
no change ) . 

When the software interrupt is executed, location Q-4 in the stack will contain the file number of 
the file that caused the interrupt . 

It is necessary to issue a call to the IQDONTWAIT intrinsic against the file in order to complete the 
request. When reading, the target parameter is ignored in the FREADcall. The data is moved to the 
array specified by the target parameter of IODDNTWAIT. 
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FUNCTIONAL RETURN 

oldstate logical 

The old state (enabled or disabled) of software interrupts is returned by this 
procedure. 

PARAMETERS 

intstate logical by value (required) 

A logical value enabling/disabling software interrupts through bit (1 5 : 1 ) as 
follows : 

=0 Disable software interrupts. 

= 1 Enable software interrupts. 

CONDITION CODES 

The condition code remains unchanged . 

SPECIAL CONSIDERATIONS 

An uncompleted FREAD/FWRITE request may be aborted by issuing an FCONTROL call with a control- 
code 43 (abort NO WAIT I/O). 

Limitations : 

• Only message (MSG) files allow soft interrupts. 

• I To more than one uncompleted FREAD/FWRITE may be outstanding for a particular file. 

• The interrupt is held off while the user is executing within MPE , with the following exceptions : 
PAUSE and I QUIA IT will allow the interrupt. The interrupt handler's return stack marker in this 
case will be set to reinvoke the intrinsic . 

• F INTSTATE may not be used with remote files. 

ADDITIONAL DISCUSSION 

MPE File System Reference Manual (30000-90236). 
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FLABELINFO 

INTRINSIC NUMBER 25 
Returns information from the file label of a disc file. (Available version G.02.00 or later.) 

SYNTAX 



BA IV I IA BA IA 

FLABELINFO C f 'name ,mode t errorcode , Items yitemoalues , it emerrors) ; 



The FLABELINFO intrinsic allows information on a specific disc file to be extracted from the file sys- 
tem whether or not the file is opened. The information returned is a subset of the information 
returned from the FF I LE I NFD intrinsic . FLABEL I NFO is not supported for remote files. 



PARAMETERS 

fname 



mode 



erporcode 



items 



itemvalues 



byte array (required) 

The name of the file terminated by a nonalphanumeric character other 
than a period (.) or a slash (/). The filename may include password, group, 
and account specifications. The file must be in the permanent file direc- 
tory. The filename also may backreference a file equation and optionally 
be preceded by an asterisk. 

integer by value (required) 

An integer specifying the valid backreferencing (to file equations) for the 

file. Valid mode values are: 

Use file equation if one exists. 

1 Must use file equation (error if one does not exist). 

2 Ignore any existing file equations. 

integer (required) 

Returns any general warnings or errors which affect the FLABELINFD call. 
Specifically, it will return an error number indicating that the call failed 
or that an error occurred in one of the specific items. An error code of 
zero indicates no errors, a positive error code indicates an error, and a 
negative error code indicates a warning. 

integer array (required) 

An array of item numbers terminated with a zero. Each item number 
describes which item is to be returned in the itemvalues array. (Refer to 
"Item#" in Table 2-4.) 

byte array (required) 

Information returned depending on the item number. (Refer to "Item 
Value" in Table 2-4.) The array contains all of the returned items. For 
example, if Item 1 and Item 2 are requested, the filename will be in the 
first eight bytes of the array , and the group name will be in the next eight 
bytes of the array. 
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itcmerrors integer array (required) 

Array of error numbers which correspond to the items specified in the item 
array. If an element of the array is negative, a warning exists for that 
item. If the element is positive, an error was detected for that specific 
item. The absolute value of the error is the file system error number. 

CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied because an error occurred. Refer to the error code and 

itemerrors parameters for specific error numbers. 

ADDITIONAL DISCUSSION 

The FFILEINFD discussion in this section. 
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The request for information from an Item# listed in Table 2-4 is granted or denied based on the 
access mode of the user : 

• Read access to the file (R). 

• Write access to the file (W). 

• Read or write access to the file (R/W). 

• Privileged call to intrinsic (P). 

• Manager of file (M). (This is AM if file is within group, otherwise SM). 

• Creator of the file (C). 

Items 1 through 3 and 6 through 24 are available to any caller. Items 4 and 5 require either creator, 
privileged, or manager access. Item 25 requires privileged, manager, or read/ write access. 

Table 2-4. Item Values Returned By FLABELINFO 



ITEM* 


ITEM VALUE 




TYPE 


UNITS 


1 


File name in file label 




BA 


8 bytes 


2 


Group name in file label 




BA 


8 bytes 


3 


Account name in file label 




BA 


8 bytes 


4 


Creator name in file label 




BA 


8 bytes 


5 


Security matrix for access 




D 




6 


Creation date (calendar format) 






7* 


Last access date (calendar f 


orma 


t) L 




8* 


Last modified date (" 


" 


) L 




9 


File code 








10* 


Number of user labels written 






11* 


Number of user labels availa 


ble 






12 


File limit 








13 


F0PTI0NS 








14 


Record size 






bytes 


15 


Block size 




D 


words 


16* 


Number of extents 








17* 


Last extent size 






sectors 


18 


Extent size 






sectors 


19* 


End of file record number 




D 




20 


File allocation time 




D 




21 


File allocation date 




L 




22* 


Number of open/close records 
(message files only) 




D 




23 


Device name 




BA 


8 bytes 


24* 


Last modify time 




D 




25* 


First user label (user label 


0) 


BA 


256 bytes 



These items may not be up to date while the file is open . 
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FLOCK 

INTRINSIC NUMBER 15 
Dynamically locks a file . 

SYNTAX 



IV LV 

FLOCK(fileman,lockcond) ; 



FLOCK provides a means of signaling that the caller temporarily wants exclusive use of a file. 

PARAMETERS 

filenum integer by value (required) 

A word supplying the file number of the file to be locked . 

lockcond logical by value (required) 

A word specifying conditional or unconditional locking by setting bit 
( 1 5 : 1 ) as follows : 

=0 Locking will take place only if the file's Resource Identification 
Number (RIN) is not currently locked. If the RIN is locked, control 
returns immediately to the calling process , with condition code CCG . 

= 1 Locking will take place unconditionally. If the file cannot be locked 
immediately , the calling process suspends until the file can be locked . 

CONDITION CODES 

The condition codes possible when lockcond bit (1 5 : 1 )= 1 are: 

CCE Request granted. 

CCG Not returned for this bit setting . 

CCL Request denied because this file was not opened with the "dynamic lock- 

ing" aoption bit (10:1) specified in the FOPEN intrinsic, or the request was 
to lock more than one file and the calling process does not possess the 
Multiple RIN (MR) capability. 

The condition codes possible when lockcond bit ( 1 5 : 1 )=0 are : 

CCE Request granted. 

CCG Request denied because the file was locked by another process. 

CCL Request denied because this file was not opened with the "dynamic lock- 

ing" aoption bit (10:1) specified in the FOPEN intrinsic, or the request was 
to lock more than one file and the calling process does not possess the 
Multiple RIN (MR) capability. 
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SPECIAL CONSIDERATIONS 

Split-stack calls permitted. 

Standard capability sufficient if only one file is to be locked dynamically. If more than one file is to 
be locked dynamically, the Multiple RIN (MR) capability is required. 

ADDITIONAL DISCUSSION 

MPE File System Reference Manual (30000-90236). 
The FDPEN intrinsic in this section . 
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FLUSHLOG 

NO INTRINSIC NUMBER ASSIGNED 



Flushes the contents of the user logging memory buffer to the logging file . 

SYNTAX 



D I 

FLUSHLOGCindea^stotMs) ; 



The FLUSHLOG intrinsic is used to write the contents of the user logging memory buffer to the disc 
destination file. This helps to preserve the contents of the memory buffer in the event of a system 
failure. This intrinsic does not write special records. 



PARAMETERS 

index 

status 



double (required) 

The parameter returned from OPENLOG that identifies the user's access to 

the logging system. 

integer (required) 

One of the following integers indicating the success/failure of the intrinsic 

call: 



Message No . 



1 

2 
3 

4 
S 
6 

7 



9 
10 



Meaning 

No error occurred for this call . 

User requested NOW AIT mode and the logging process is 
busy. 

Parameter out of bounds in logging intrinsic . 

Request to open or write to a logging process that is not 
running. 

Incorrect index parameter passed to a logging intrinsic . 

Incorrect mode parameter passed to a logging intrinsic. 

User request denied because logging process is suspended . 

Illegal capability. Must have User logging (LG) and 
System Supervisor (OP) capabilities to use a logging 
intrinsic. 

Incorrect password passed to a logging intrinsic . 

Error occurred while writing to the logging file. 

Invalid DST passed to a logging system intrinsic. 
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Message No . 

12 
13 
14 
15 
16 

CONDITION CODES 

The condition code remains unchanged . 

SPECIAL CONSIDERATIONS 

User Logging (LG) and System Supervisor (OP) capability required. 

ADDITIONAL DISCUSSION 

"User Logging" in Section III. 



Meaning 

System is out of disc space , logging cannot proceed . 
No more logging entries. 
Invalid access to logging file. 
End-of-file on user log file. 
Invalid logging identifier . 
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FMTCALENDAR 

NO INTRINSIC NUMBER ASSIGNED 



Converts any calendar date with the same format as the CALENDAR intrinsic into the format: "FRI , 
JAN 18, 1985". 



SYNTAX 



LV BA 

FMTCALENDARCdate,stringr) ; 



PARAMETERS 

date logical by value (required) 

A logical value representing any calendar date with the same format as the 
CALENDAR intrinsic: 

Bits (7:9) - The day of the year. 

Bits (0:7) - The year of the century. 

string byte array (required) 

A 17 -character byte array in which the formatted calendar date is return- 
ed. If the day of the month is less than 10, an additional blank will 
precede it, for example: "FRI, JAN 8, 1985". 

CONDITION CODES 

The condition code remains unchanged. 

ADDITIONAL DISCUSSION 

"Formatting Calendar Data and Time Information" in Section V. 
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FMTCLOCK 

NO INTRINSIC NUMBER ASSIGNED 



Converts the time of day with the same format as the CLOCK intrinsic, into the format: "12:39 
AM". 

SYNTAX 



DV BA 

FMTCLOCK (time,string) ; 



PARAMETERS 

time double by value (required) 

A double-word value representing the time of day in the same format as 
the CLOCK intrinsic : 

Word 1 : 

Bits (8:8) - The minute of the hour. 

Bits (0:8) - The hour of the day. 

Word 2: 

Bits {i:9>) - The tenths of seconds. 

Bits (0:8) - The seconds. 

string byte array (required) 

An 8 -character byte array in which the formatted time of day is returned. 
If the hour is a single digit (i.e. prior to 10:00) the array will contain a 
leading blank as follows: " 7:39 AM". 

CONDITION CODES 

The condition code remains unchanged. 

ADDITIONAL DISCUSSION 

"Formatting Calendar Date and Time Information" in Section V. 
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FMTDATE 

NO INTRINSIC NUMBER ASSIGNED 



Converts calendar date and time of day with the same format as the CALENDAR and CLOCK intrinsics, 
into the format: "FRI, JAN 18, 1985, 12:39 AM". 

SYNTAX 



LV DV BA 

FMTDATE (.date, time ,stx>ing'y ; 



PARAMETERS 

date logical by value (required) 

A logical value with the same format as the CALENDAR intrinsic : 

Bits (7:9) - The day of the year. 

Bits (0:7) - The year of the century. 

time double by value (required) 

A double value with the same format as the CLOCK intrinsic : 

Word 1 : 

Bits (8:8) - The minute of the hour. 

Bits (0: 8) - The hour of the day. 

Word 2: 

Bits (8:8) - The tenths of seconds. 

Bits (0:8) - The seconds. 

string byte array (required) 

A 27 -character byte array in which the formatted date and time are 
returned. If the day of the month is less than 10, an additional blank will 
precede it. Similarly, if the time is earlier than 10:00 (one digit), an addi- 
tional blank will also precede the time, for example: "FRI, JAN 8, 
1985, 7:39 AM". 

CONDITION CODES 

The condition code remains unchanged . 

ADDITIONAL DISCUSSION 

"Formatting Calendar Date and Time Information" in Section V. 
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FOPEN 

INTRINSIC NUMBER I 



Used to establish access to a file and optionally , to define the physical characteristics of the file prior 
to access. 



SYNTAX 



I 0-V BA LV LV IV 

filenum: "FDPEHCf ornaldesignator ,foptidns ,aoptions s x*ecsize , 

BA BA IV IV IV 

device ,fornmsg ,userlabels ,blockj 'actor ,numbuffers 

DV IV IV ' IV 
filesize ,numextents , initial loc ,filecode ) ; 



The FDPEN intrinsic makes it possible to access a file. In the FOPEN intrinsic call, a particular file 
may be referenced by its formal file designator, described in Section IV. When the FDPEN intrinsic is 
executed, it returns a file number to the user's process by which the system uniquely identifies the 
file. This file number, rather than the file designator, is used by subsequent intrinsics in referencing 
the file. 



FUNCTIONAL RETURN 



filenum 



integer 

An integer file number used to identify the opened file in subsequent in- 
trinsic calls. 



PARAMETERS 

formaldesignator 



byte array (optional) 

This array contains a string of ASCII characters interpreted as a formal file 
designator. This string must begin with a letter; contain alphanumeric 
characters, slashes, or periods; and terminate with any nonalphanumeric 
character except a slash (/) or a period ( .). If the string is the name of a 
system -defined file, it can begin with a dollar sign ($); if it is the name of 
a user -predefined file, it can begin with an asterisk (*). New KSAM files, 
unlike standard files, must be opened with a unique name. Effective with 
the G.02.00 release, the remote location of a device may be specified in 
formaldesignator as filename :envid. 

Default: A temporary nameless file is assigned that can be read from or 
written to, but not saved. 
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f options logical by value (optional) 

The foptions parameter allows you to specify different file characteristics 
by setting corresponding bit groupings in a 16 -bit word. The correspon- 
dence is from right to left , beginning with bit 15. These characteristics are 
as follows, proceeding from the rightmost bit groups to the leftmost bit 
groups in the word. The bit settings are summarized in Figure 2-1, 
"Foptions Bit Summary, found in the description of the FGETINFO 
intrinsic. 

Bits (14:2) - Domain f opt ion. 

The file domain to be searched by MPE to locate the file : 

=00 The file is a new file , created at this point. No search is necessary. 

=01 The file is an old file, and the system file domain should be searched. 

= 10 The file is an old temporary file, and the job file domain should be 
searched . 

= 11 The file is an old file, located first by searching the job file domain 
then, if it is not found, by searching the system file domain. 

Bit ( 1 3 : 1 ) - ASCII/binary f option . 

The code (ASCII or binary) in which a new file is to be recorded when it is 
written to a device that supports both codes. In the case of disc files, this 
also affects padding that can occur when a direct -write intrinsic call 
(FWRITEDIR) is issued to a record that lies beyond the current logical end- 
of-file indicator. In ASCII files, any dummy records between the previous 
end -of -file and the newly written record are padded with blanks. In bi- 
nary files, such records are padded with binary zeros. By default, mag- 
netic tape and serial disc files are treated as ASCII files; and foreign disc 
files are treated as binary. This bit has the following settings: 

=0 Binary file. 

= 1 ASCII file. 

Bit(10:3) - Default file designator f opt ion. 

The actual file designator is equated with the formal file designator 

specified in FQPEN if: 

• No explicit or implicit :FILE command equating the formal file desig- 
nator to a different actual file designator occurs in the job or session . 

• The "Disallow file equation" f opt ion is true (bit (5:1)=1). Note that 
a leading "»" in a formal designator can effectively override the disal- 
low file equation f option. 
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The bit settings are : 

=000 The actual file designator is the same as the formal file designator. 

=00 1 The actual file designator is $STDL I ST. 

=010 The actual file designator is $NEHPASS. 

=01 1 The actual file designator is $0LDPASS. 

= 1 00 The actual file designator is $STDIN. 

= 101 The actual file designator is $STD I NX. 

= 110 The actual file designator is $NULL. 

Bits (8:2) - Record format f option. 

The format in which the records in the file are recorded , indicated by the 

following bit settings : 

=00 Fixed-length records. The file is composed of logical records of 
uniform length. Foreign discs always have fixed -length records. 

=01 Variable-length records. The file contains logical records of varying 
length. This format is restricted to records that are written in 
sequential order. The size of each record is recorded internally. The 
actual physical record size used is determined by multiplying the 
record size (specified or default) plus one by the blocking factor, and 
adding one word for the end-of -block indicator. 

In the case of new files, this option is not allowed when NOBUF is 
specified. In such a case, the record format will be changed by these 
bit settings internally to undefined -length records, discussed below. 
If NOBUF is specified, then reads/writes are performed in terms of 
the entire block, not just the record; thus you must set up the vari- 
able structure before attempting an FWRITE. (Refer to record for- 
mats in the MPE File System Reference Manual (30000-90236). ) 

= 10 Undefined-length records. The file contains records of varying 
length that were not written using the variable -length f option (bits 
(8:2)=01). All files not on disc or magnetic tape are treated as con- 
taining undefined -length records by default. The file system makes 
no assumption about the amount of data that is useful. The user 
must determine how much data is required. 

For undefined -length records, only the data supplied is written with 
no information about its length. Undefined-length records are sup- 
ported by all devices; fixed- and variable -length records are sup- 
ported by disc and magnetic tape devices only. To state this another 
way: disc and magnetic tape devices support all record formats, 
whereas all other devices support only undefined length records. 
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Bit (7:1) - Carriage control f opt ion. 

If selected , this specifies that you will supply a carriage control directive in 
the calling sequence of each FWRITE call that writes records onto the file. 
This bit may be set as follows : 

=0 No carriage control directive expected. 

= 1 Carriage control directive expected . 

Carriage control is defined only for character-oriented (ASCII) files. This 
option and the "binary" option are mutually exclusive, and attempts to 
open new files with both binary and carriage control directives will result 
in an access violation. This option is a physical attribute of the file and its 
state cannot be modified when opening an old disc file. 

A carriage -control character passed through the control parameter of 
FWRITE is recognized as such and acted upon for files that have carriage 
control specified in FOPEN. Embedded control characters are treated strict- 
ly as data on files for which no carriage control is specified, and they do 
not invoke spacing for such files. You may specify spacing action on files 
for which carriage control has been specified, either by embedding the con- 
trol in the record, indicated with a control parameter of 1 in the call to 
FWRITE, or by sending the control code directly via the control parameter 
of FWRITE. 

A carriage -control character sent to a file on which the control cannot be 
executed directly (for example , line spacing characters sent to a disc or tape 
file), will result in having the control character embedded as the first byte 
of the record. Thus, the first byte of each record in a disc file having 
carriage-control characters enabled contains control information. 
Carriage -control characters sent to other types of files will result in trans- 
mission of the control to the driver. 

The control codes %400 through %403 are remapped to %100 through %103, 
so that they fit into one byte and thus can be embedded. Records written 
to the line printer with one of the above control codes should contain only 
control information. 

A record written with one of the above controls and no data (count=0, or 
embedded control and count= 1 ) will not cause physical I/O of any sort . 

For the purpose of computing record size, carriage control information is 
considered by the file system to be part of the data record. As such, 
specifying the carriage control option adds one byte to the record size when 
the file is originally created. For example, a specification of 
"REO-132,1 ,F,ASCII ;CCTL" results in a recsize of 133 characters. 

As a general rule you may read the entire file (the size of which is returned 
in the recsize parameter of FGETINFOor itemft 6 (record) of FFILEINFO). 
(Refer to Table 2-3 found in the description of the FF I LE I NFD intrinsic.) 
However, on writes of files for which carriage control characters are 
specified the data transferred is limited to recsize- 1 unless a control of 1 is 
passed, indicating the data record is prefixed with embedded carriage con- 
trol characters . 
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Bit (6:1) - Labeled tape f option. 

= 1 Labeled tapes . 

=0 No labeled tapes. 

Bit (5:1) - Disallow : FILE equation f option. 

This option ignores any corresponding :FILE command, so that the 
specifications in the FOPEN call take effect (unless pre-empted by those in 
the file label, for disc files). Note that a leading * in a formal designator 
can effectively override the disallow file equation f opt ion . 

=0 Allow :FILE. 

= 1 Disallow :FILE. 

Bits (2:3) - File type f option. 

Determines the type of file to create for a new file . If the file is old , this 

field is ignored . 

=000 Ordinary file. 

=001 KSAMfile. 

=010 Relative I/O file. 

= 100 Circular file. 

= 110 Message file . 



NOTE 



The default designator f opt ion, bits (10:3), offers several 
choices for default file designators. Any value used other than 
000 for "filename" will override the File Type field. 



Specification of both the KSAM and RIO options result in an access viola- 
tion communicated by returning CCL. Specifying RIO in a :FILE com- 
mand will override the KSAM option in the FOPEN call. 

Bits (0:2) - Reserved for MPE. Should be set to zero. 

aoptions logical by value (optional) 

The aoptions parameter permits you to specify up to seven different access 
options established by bit groupings in a 16 -bit word. The correspondence 
is from right to left, beginning with bit 15. These access options are 
described below, proceeding from the rightmost bit groups to the leftmost 
bit groups in the word. The bit settings are summarized in Figure 2-2, 
"Aoptions Bit Summary", found in the description of the FGETINFO 
intrinsic. 

Default: All bits are set to zero. 
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Bits (12:4) - Access Type aoptions. 

The type of access allowed for this file is specified by the following bit 

settings : 

=0000 READ access only. FWRITE, FUPDATE, and FWRITEDIR intrinsic 
calls cannot reference this file. The end -of -file is not changed; 
the record pointer starts at 0. 

=0001 WRITE access only. Any data written in the file prior to the cur- 
rent FDPEN request is deleted. The FREAD, FREADSEEK, 
FUPDATE, and FREADD I R intrinsic calls cannot reference this file. 
The end-of-file is set to 0; the record pointer starts at 0. On 
magnetic tape an EOF mark will be written to the tape when the 
file is closed even if no data is written. 

=0010 WRITE access only, but previous data in the file is not deleted. 
The FREAD, FREADSEEK, FUPDATE, and FREADD I R intrinsic calls 
cannot reference this file. The end-of-file pointer is not chang- 
ed, the record pointer starts at 0. Therefore, data will be over- 
written if an FWRITE is done. The system will change this value 
to APPEND for message files. 

=0011 APPEND access only. The FREAD, FREADDIR, FREADSEEK, 
FUPDATE, FSPACE, FPDINT, and FWRITEDIR intrinsic calls can- 
not reference this file. The end-of-file pointer is used to set the 
record pointer prior to each FWRITE. For disc files it is updated 
(in an internal file system table) after each FWRITE. Thus, data 
cannot be overwritten. 

=0100 INPUT/OUTPUT access. Any file intrinsic except FUPDATE can 
be issued for this file. The end-of-file pointer is not changed, 
the record pointer starts at 0. Not valid for message files. 

=0101 UPDATE access. All file intrinsics, including FUPDATE can be is- 
sued for this file. The end-of-file pointer is not changed; the 
record pointer starts at 0. Not valid for message files. 

=0110 EXECUTE access. Allows user who is running in Privileged Mode 
input/output access to any loaded file. The end-of-file pointer is 
not changed, the record pointer starts at 0. Not valid for message 
files. 
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Bit (1 1 : 1 ) - Multirecord aoption. 

Signifies that individual read or write requests are not confined to record 
boundaries. Thus, if the number of words or bytes to be transferred 
(specified in the tcount parameter of the read or write request) exceeds the 
size of the physical record (i.e. block) that is referenced, the remaining 
words or bytes are taken from subsequent successive records until the num- 
ber specified by tcount has been transferred . 

For message (MSG) files, the file system sets this bit to zero. This option is 
available only if the inhibit buffering aoption, described below, is also 
selected. 

=0 Non-multirecord mode (NOMULTI). 

= 1 Multirecord mode (MULTI ) . 

Bit (10:1) - Dynamic Locking aoption (disc file only) . 
Indicates use of the FLOCK and FUNLOCK intrinsics to dynamically permit or 
restrict concurrent access to the file by other processes at certain times. 
The user process can continue this temporary locking/unlocking until it 
closes the file. Dynamic locking/unlocking is made possible through a 
Resource Identification Number (RIN) assigned to the file and temporarily 
acquired by FOPEN. The calling process and other processes must use the 
RIN in cooperation to guarantee the integrity of the file , as discussed under 
"Resource Management" in Section III. Non -cooperating processes are al- 
lowed concurrent access at all times, unless other provisions prohibit this. 
You must have LOCK access at account , group , and file levels for FOPEN to 
grant the dynamic locking aoption. (LOCK access is available if LOCK, 
APPEND, or WRITE access is set for you at these levels.) 

=0 Disallow dynamic locking/unlocking. 

= 1 Allow dynamic locking/unlocking. A disc file may be accessed concur- 
rently only if all FDPEN requests for the file specify dynamic locking. 
An FOPEN request that disagrees with the current access , if any , will 
fail. This bit is ignored for files not residing on disc. 
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Bits (8:2) - Exclusive aoption. 

This aoption specifies whether you have continuous EXCLUSIVE access to 
this file, from the time it is opened to the time it is closed. This option of- 
ten is used when performing some critical operation , such as updating the 
file. 

=00 Default value. If the "READ access only" aoption is selected, 
SEMI -exclusive access (8: 2)= 10 takes effect. Otherwise, 

EXCLUSIVE access (8: 2)= 01 takes effect. Regardless of which access 
is selected, FGETINFD will report (8:2)=00. 

=01 EXCLUSIVE access. After this file is opened, any additional F0PEN 
requests, whether issued by this process or another process, are 
prohibited until this process issues the FCL0SE request or terminates. 
If any process already is accessing this file when the FDPEN call is is- 
sued, CCL is returned to the calling process. If another FQPEN call is 
issued for this file while the "EXCLUSIVE access" aoption is in ef- 
fect, an error code is returned to that calling process. The 
"EXCLUSIVE access" aoption can be requested only by users allowed 
the LOCK access mode by the security provisions for the file. For 
message files, there can be only one reader and one writer. 

= 10 SEMI -exclusive access. After the file is opened, concurrent output 
access to this file via another FOPEN request is prohibited, whether is- 
sued by this process or another process, until this process issues the 
FCL0SE request or terminates. A subsequent request for the 
"INPUT/OUTPUT" or "UPDATE" aoption access type will obtain 
"READ" access. Other types of read access, however, are allowed. 
If a process already has OUTPUT access to the file when this FOPEN 
call is issued, a CCL error code is returned to the calling process. If 
another FOPEN call that violates the READ -only restriction is issued 
while the "SEMI -exclusive" aoption is in effect, that call fails and an 
error code is returned to the calling process. Semi -exclusive access 
can be requested only by users allowed the LOCK access mode by the 
security provisions for the file. For message files there can be multi- 
ple readers, but only one writer. 

= 11 SHARE access. After the file is opened , permits concurrent access to 
this file by any process, in any access mode, subject to other basic 
MPE security provisions in effect. For any message file there can be 
multiple readers and multiple writers. 

Bit (7:1) - Inhibit buffering aoption. 

When selected, this aoption inhibits automatic buffering by MPE and al- 
lows input/output to take place directly between the user's data area and 
the applicable hardware device. 
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=0 Allow normal buffering (BUF). 

= 1 Inhibit buffering (NOBUF). 

NOBUF access is oriented to physical block transfer rather than logical 
record transfer. If this option is specified with the variable record format 
and the file is not variable length record format, the format will be chang- 
ed internally to undefined length record format. Thus, you are responsible 
for buffer management. When performing an FWRITE, you will have to 
set up the variable structure. (Refer to the File System Reference Manual 
(30000-90236) for a discussion of record formats.) 

With NOBUF access, you have responsibility for blocking and deblocking of 
records in the file. To be consistent with files built using buffered I/O, 
records should begin on word boundaries. When the information content of 
the record is less than the defined record length , pad the record with blanks 
if the file is ASCII, or with zeros if the file is binary. 

The record size and block size for files manipulated under NOBUF access 
follow the same rules as those files that are created using buffering. The 
default blocking factor for a file created under NOBUF is 1 . 

When a NOBUF file is opened without multirecord access, the amount of 
data transferred per read or write is limited to a maximum of one block. 

The end -of -file, next record pointer, and record transfer count are main- 
tained in terms of logical records for all files. The number of logical 
records affected by each transfer is determined by the size of the transfer. 

Transfers always begin on a block boundary . Those transfers which do not 
transfer whole blocks leave the next record pointer set to the first record in 
the next block. The end -of -file pointer always points at the last record in 
the file. 

For files opened with NOBUF access, the FREADDIR, FWRITEDIR, and 
: POINT in trinsics treat the recnum parameter as a block number. 

Non-RIO access to a RIO file can be indicated by specifying the NOBUF 
option. In this case the physical block size from FFILEINFO should be used 
to determine the maximum transfer length. (Refer to Table 2-3, Item 
#21 found in the description of the FFILEINFO intrinsic.) The FGETINFO 
blksize parameter may also be used . 

For message files, the file system sets bit (7:1)=0. However, readers may 
open a message file with NOBUF if they are in copy mode; this determines 
whether they will be accessing the file record by record or by block. Thus 
for readers of message files , bit (7 : 1 ) has the following settings : 

=0 Read by logical record . 

= 1 Read by physical block . 

Writers must open message files with NOBUF if they are in copy mode; 
they will access the file block by block 
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Bits (5:2) - MULTI access mode aoption. 

This feature permits processes located in different jobs or sessions to open 

the same file . 

=00 No MULTI access. 

=01 Only intra -job MULTI access allowed; this is the same as specifying 
the MULTI option in a : FILE command. 

= 10 Inter -job MULTI access allowed; this is the same as specifying the 
GMULTI option in a : FILE command. 

= 11 Undefined. If this is specified, the FDPEN call will be rejected with 
an error code of 40: "ACCESS VIOLATION". 

For message files, the file system changes bits (5:2)=00 to bits (5: 2)= 10 to 
allow global MULTI access. 

Bit (4: 1 ) - NOW AIT I/O aoption. 

This bit allows the accessor to initiate an I/O request and to have control 
returned before the completion of the I/O. The NO WAIT I/O aoption im- 
plies the NOBUF aoption; if you do not specify NOBUF, the file system 
does it for you. Also, multirecord access is not available. This option is 
not available if the file is located on a remote computer. 

= 1 NOW AIT I/O in effect. 

=0 NOW AIT I/O not in effect. 

You must be running in Privileged Mode to use NO WAIT. 

Bits (3:1) - File copy aoption. 

This feature permits any file to be treated as a standard sequential file so 

that the file can be copied by logical record or physical block to another 

file. 

=0 The file will be accessed in its native mode, i.e. a message file will be 
treated as a message file, a KSAM file as a KSAM file. 

= 1 The file is to be treated as a standard, sequential file with variable 
length records. For message files this allows nondestructive reading of 
an old message file at either the logical record or physical block record 
level. Only block level access is permitted if the file has message -file 
format to prevent incorrectly formatted data from being written to the 
message file while it is unprotected. In order to access a message file in 
copy mode, a process must have exclusive access to the file. 

Bits (0:3) - Reserved for MPE. Should be set to zero. 

recsize integer by value (optional) 

An integer indicating the size of the logical records in the file. If a positive 
number , this represents words ; bytes are represented by a negative number . 
A newly created file will have this value recorded permanently in the file 
label. This value indicates the maximum logical record length allowed if 
the records in the file are of variable length . 
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Binary files are word oriented. A record size specifying an odd byte count 
for a binary file is rounded up by FOPEN to the next highest even number. 

ASCII files may be created with logical records which are an odd number of 
bytes in length. Within each block, however, records begin on word 
boundaries. 

For either ASCII or binary files with fixed or undefined length records, 
the record size is rounded up to the nearest word boundary. For example, a 
recsize specified as -106 for an ASCII file is 106 characters (53 words) in 
length. A recsize of -1 1 3 for a binary file is 1 14 characters (57 words) in 
length. The rounded sizes should be used in computations for block] actor or 
block size. When a foreign disc is opened, recsize is forced to 128 words. 
(IBM diskettes are forced to 64 words.) 

Default: The default value is the configured physical record width of the 
associated device. 

device byte array (optional) 

Contains a string of ASCII characters terminating with any nonal- 
phanumeric character except a slash (/) or period (.), designating the 
device on which the file is to reside, and optionally specifying density for 
tape files (DEN= parameter), and/or environment files for the HP 26 8x 
page printer (ENV* parameter). This parameter may be specified in one of 
the following forms: devclass or Idev. The devclass form represents a 
device class name of up to eight alphanumeric characters beginning with a 
letter, as for example , DISC or TAPE. If the devclass form is specified, the 
file is allocated to any available device in that class. To open a file which 
is to reside on a private volume, you must specify a device class which in- 
cludes those disc drives upon which the home volume set is mounted; the 
file then is allocated to any of the home volume set's drives that fall within 
that device class. 

The logical device number (Idev) consists of a three -byte numeric string 
specifying a particular device. 

If you open a foreign disc file, device must be either a foreign disc class 
name or the Idev of a disc in a foreign disc class. If you specify Idev, the 
disc should be mounted on the drive prior to the FDPEN. Otherwise it may 
be assumed to be a serial disc by the system. Any of the forms may be used 
to reference files on a remote computer by preceding the device or volume 
specification with dsdevice*. 

Effective with the G.02.00 release, the remote location of a device may be 
specified with the device parameter as nodenamettldev ,VTERM<CR>. 



NOTE 



When opening a magnetic tape as shared for a second time , the 
device must be opened by Idev instead of devclass. This is to en- 
sure that the System Operator does not get confused by a second 
tape request. The Idev may be programmatically obtained 
through FGETINFO. 
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To specify density when writing to the tape files, the keyword "DEN=" is 
used. The "DEN=" keyword must be preceded by a semicolon (;), which 
indicates to the system that a keyword follows. Note that if the device 
parameter is specified, a semicolon must terminate the device string. If 
device string is not specified but the device parameter is , then a semicolon 
must be the first character of the device parameter. The entire device pa- 
rameter string must be terminated by a carriage return . 

The keyword DEN=" is applicable only when writing to tape on a tape drive 
that supports more than one density. The keyword DEN=" is ignored at all 
other times. 

When reading from tape, the density selected by the user at FOPEN time 
will be ignored. For example, when reading from a tape, a 1600 BPI tape 
will satisfy an FDPEN request which specified ;DEN=6250, and vice versa. 
The following examples show the correct syntax for the "DEN=" keyword: 

BYTE ARRAY DEVICEC0:13):="TAPE;DEN=6250",%15 
BYTE ARRAY DEVICEC0:9):=";DEN=6250",%15; 



NUM:=FGPEN(FILEX,%4,%4 } , DEVICE); 

If you are opening a HP 268x page printer file, you may specify an option- 
al printing environment for your job. The printing environment is defined 
as all of the characteristics of the printed page which are not part of the 
data itself, including the page size, the margin width, the character set, 
the orientation (horizontal or vertical) , and the name of forms you wish to 
use. Such information is contained in the "environment" file. 

If you do not specify an environment file , FDPEN assumes that you want to 
use the default printer environment. Hewlett-Packard provides a number 
of prepared environment files, which reside in the HPENV (G.00.00 and 
later) or ENV2680A (earlier versions) group of the SYS account. For in- 
formation on how to build your own printing environments, refer to the 
IFS/3000 Reference Manual (36580-90001). 

To specify your own printer environment you must also assign the keyword 
"ENV=" , followed by the name of your environment file, to the device ar- 
ray in the form EW-enVi-ronment filename , and terminate the array 
with a carriage return. You must also include a semicolon ( ;) between the 
device class name and the "ENV" keyword. For example, if PP is the device 
class name configured for your HP 26 8x printer: 

EQUATE CR=%15; 

BYTE ARRAY DEVICEC0:16):="PP;ENV=MYENVFILE",CR; 

e 

NUM : =F0PEN (F I LEX, 7.4, %4,, DEVICE); 
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Any environment you select remains active until it is replaced by a new 
environment or until you FCLDSE the printer. If the printer has been 
opened with the MULTI access aoption (for example, as $STDLIST), a 
selected environment remains active until replaced or until the final 
FCLDSE of the printer. 

For Interprocess Communication (IPC) , this field is relevant only if this is a 
new message file . The device field must either be omitted or must specify a 
disc; specification of any device other than disc opens the device. When 
this occurs, the file is no longer a message file. 

Default: DISC. 

formnsg byte array (optional) 

Contains a forms message that can be used for such purposes as telling the 
System Operator what type of paper to use in the line printer. This mes- 
sage must be displayed to the System Operator and verified before this file 
can be printed on a line printer. The message itself is a string of ASCII 
characters terminated by a period. The maximum number of characters al- 
lowed in the array is 49, including the terminating period. Arrays with 
more than 49 characters are truncated by MPE. 

This array is also used for tape label information if bit (6 : 1 ) of the f options 
parameter is set. The tape label information is formatted as follows: 

. ivolumeidl , type [ 7 exp I , seql 1 ] ] ; 

The period is required so that the tape label information is not mistaken for 
a forms message by MPE. 

Volwneid Consists of six or fewer printable characters that identify the 
volume. In a multi -volume set, only the first volumeid can be 
specified. 

type Three alphabetic characters that identify label type informa- 

tion . The options are : 

ANS- ANSI standard labels. (Default) 
IBM- IBM standard labels. 

expdate Month/day/year of the expiration date of the file or the date 
after which the information contained in the file is no longer 
useful. The file can be overwritten after this date. Default is 
00/00/00, meaning that the file can be overwritten im- 
mediately. In a volume set, file expiration dates must always 
be equal to or earlier than the date on the previous file. 
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seq One of the following methods to specify the position of the 

file in relation to other files on the tape : 

A which causes a search of all volumes until the file is 
found. 

An unsigned integer (1-9999) that specifies the position 
of the file relative to the current file on the tape. 

ADDF causes the tape to be positioned so as to add a new 
file on the end of the volume (or last volume in a multi- 
volume set). 

NEXT will position the tape at the next file on the tape. 
If this is not the first FDPEN for the file and a rewind 
occurred on the last close , then the position will remain 
at the beginning of the previous file . ' 

Default: NEXT. 



userlabels 



integer by value (optional) 

An integer specifying the number of user -label records to be written for 
this file. Applicable to new disc files only. The maximum number of user 
labels allowed varies from file to file. It depends on the final blockf actor 
and recsize used, as well as whether you specified fixed, variable or un- 
defined length records. If you specify more user labels than will fit in the 
254 sectors following the MPE file label, an error occurs and the FQPEN 
fails. 



blookfactor 



Default: The default number of user -label records is zero. 

integer by value (optional) 

An integer containing the size of the buffer to be established for the file, 
specified as a number equal to the number of logical records per block . For 
fixed-length records, blockf actor is the actual number of records in a 
block. For variable -length records, blockf actor is interpreted as a multi- 
plier used to compute the block size (maximum recsize*blockf actor) . For 
undefined-length records, blockf actor is always one logical record per 
block. The block factor value specified by you may be overridden by MPE. 
The valid range for blockf actor is from 1 through 255. Specification of a 
negative or zero value results in the default blockf actor setting. Values 
greater than 255 are defaulted to 255. The blockf act or establishes the 
physical record size on disc and magnetic tape files . Note that for NOBUF 
files the default blocking factor is one. The blockf actor for foreign disc 
files is 1 . 



Default: Calculated by dividing the specified recsize (in words) into the 
configured block size. This value is rounded downward to an integer that is 
never less than 1. 
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numbuffers 



filesize 



integer by value (optional) 

A 16 -bit word whose bits specify the number of buffers, number of copies, 

and output priority . 

Default: The default values of all bit groupings are taken. 

Bits (11:5) - Number of buffers. 

Specifies the number of buffers to be allocated to the file. This parameter 
is not used for files representing interactive terminals, because a system - 
managed buffering method is always used in such cases. If omitted, set to 
zero, the default value of 2 is set by MPE. 

For message files, a value between 2 and 31; default is 2. This parameter 
must not exceed the physical capacity of the file. 

Bits (4:7) - Number of Copies. 

For spooled output devices only , specifies the number of copies of the entire 
file to be produced by the spooling facility . This can be specified for a file 
already opened (for example, SSTDLIST), in which case the highest value 
supplied before the last FCLOSE will take effect. The copies do not appear 
contiguously if the System Operator intervenes or if a file of higher output 
priority becomes READY before the last copy is complete. This parameter 
is ignored for nonspooled output devices. 

Default : The value is 1 . 

Bits (0:4) - Output Priority. For spooled devices only. 
Specifies the output priority to be attached to this file. This priority is 
used to determine the order in which files are produced when several are 
waiting for the same device. This parameter must be a number between 1 
(lowest priority) and 13 (highest priority), inclusive. If this value is less 
than the current outfence set by the System Operator, file printing/punch- 
ing is deferred until the operator raises the output priority of the file or 
lowers the outfence. This parameter can be specified for a file already 
opened (for example, SSTDLIST), in which case the highest value supplied 
before the last FCLOSE takes effect. This parameter is ignored for non- 
spooled devices . 

Default: 8. 

double by value (optional) 

A double -word integer specifying the maximum file capacity. For 
variable- and undefined-length records the capacity is expressed in blocks. 
For fixed -length records the capacity is expressed in logical records. The 
maximum file size is 2 sectors. However, some other file options, such as 
the blocking factor, may prevent the maximum file size from being 
reached. In general, the filesize is determined by the extent size and the 
number of extents (maximum- 3 2). 



The filesize for foreign disc files is set to the maximum physical size of the 
disc as determined by its subtype. 
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For message files, the number of records is rounded up to completely fill 
the last block and to make the last extent the same size as the other extents. 
Two additional records are included for the open and close records. 
Because of spare tracks or remapped tracks , the logical size will usually be 
smaller than the physical size. 

Default : 1023 logical records . 



numextents 



integer by value (optional) 

An integer specifying the maximum number of extents (integral number of 
contiguous disc sectors) that can be dynamically allocated to the file as 
logical records are written to it. The size of each extent is always calcu- 
lated in terms of physical records. When the file is type F (fixed) file size is 
the number of logical records; thus it will be divided by the blockf actor to 
determine the number of physical records (blocks). If the file is variable 
length or undefined length, filesize is the number of physical records. 
Then, the number of physical records required for the system file label, 
and user labels (if any), are added to the number of physical records 
required for data. To determine extent size, this number is divided by the 
requested numextents to determine extent size. The result rounded up, is 
the number of physical records per extent. This is then used to determine 
the actual number of extents and the size of each . If specified , numextents 
must be an integer from 1 to 32. A zero or negative value results in the 
default setting. Any value >32 will automatically be set to 32. 



Default: 8 extents. 



NOTE 



Extents are allocated on any disc in the device class specified in 
the device parameter when the file was created. If it is neces- 
sary to ensure that all extents of a file are on a particular disc , 
a single disc device class or a logical device number must be used 
in the device parameter. 



initialloc 



integer by value (optional) 

An integer specifying the number of extents to be allocated to the file when 
it is opened. This must be an integer from 1 to 32. If an attempt to allo- 
cate the requested disc space fails, the FDPEN intrinsic returns an error 
condition code to the calling program. 



Default: 1 extent. 



filecode 



integer by value (optional) 

An integer recorded in the file label and made available for general use to 
anyone accessing the file through the FGETINFD intrinsic. For this param- 
eter, any user can specify a positive integer ranging from to 1023. This 
parameter is used for new files only when it is positive and the process is 
running in user mode. If your process is running in Privileged Mode, you 
can specify a negative integer for filecode when initially opening a file. 
Then, any future accesses of the "privileged" file must be requested in 
Privileged Mode. A process running in user mode cannot open a file that 
has a negative filecode. Also, if the process supplies a non-zero parameter, 
the filecode must match the one originally specified for the file. The 
following integers have meanings predefined by Hewlett-Packard: 
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Integer 



Mnemonic Meaning 



1024 


USL 


1025 


BASD 


1026 


BASP 


1027 


BASFP 


1028 


RL 


1029 


PROG 


1031 


SL 


1035 


VFDRM 


1036 


VFAST 


1037 


VREF 


1040 


XLSAV 


1041 


XLBIN 


1042 


XLDSP 


1050 


EDITQ 


1051 


EDTCQ 


1052 


EDTCT 


1054 


TDPDT 


1055 


TDPQM 


1056 


TDPP 


1057 


TDPCP 


1058 


TDPQ 


1059 


TDPXQ 


1060 


RJEPN 


1070 


QPRQC 


1080 


KSAMK 


1083 


GRAPH 


1084 


SD 


1090 


LDG 


1100 


NDDC 


1101 


WDICT 


1102 


WCDNF 


1103 


W2601 


1110 


PCELL 


1111 


PFORM 


1112 


PENV 


1113 


PCCMP 


1114 


RASTR 


1130 


DPTLF 


1131 


TEPES 


1132 


TEPEL 


1133 


SAMPL 


1139 


MPEDL 


1140 


TSR 


1141 


TSD 


1145 


DRAW 


1146 


FIG 


1147 


FONT 


1148 


COLOR 


1149 


D48 


1152 


SLATE 


1153 


SLATW 



User Subprogram Library 

Basic Data 

Basic Program 

Basic Fast Program 

Relocatable Library 

Program File 

Segmented Library 

VPLUS Forms File 

VPLUS Fast Forms File 

VPLUS Reformat File 

Cross Loader ASCII File (SAVE) 

Cross Loader Relocated Binary File 

Cross Loader ASCII File (DISPLAY) 

Edit Quick File 

Edit KEEPQ File (COBOL) 

Edit TEXT File (COBOL) 

TDP Diary File 

TDP Proof Marked QMARKED 

TDP Proof Marked non -COBOL File 

TDP Proof Marked COBOL File 

TDP WorkFile 

TDP WorkFile (COBOL) 

RJE Punch File 

QUERY Procedure File 

KSAM Key File 

GRAPH Specification File 

Self -Describing File 

User Logging Log File 

HPWORD Document 

HPWORD Hyphenation Dictionary 

HPWORD Configuration File 

HPWORD Attended Printer Environment 

IFS/3000 Character Cell File 

IFS/3000 Form File 

IFS/3000 Environment File 

IFS/3000 Compiled Character Cell File 

Graphics Image in RASTR Format 

OPT/3000 Log File 

TEPE/3000 Script File 

TEPE/3000 Log File 

APS/3000 Log File 

MPEDCP/DRP Log File 

HPToolset Root File 

HPToolset Data File 

Drawing File for HPDRAW 

Figure File for HPDRAW 

Reserved 

Reserved 

Reserved 

Compressed SLATE File 

Expanded SLATE File 
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Integer 



Mnemonic Meaning 



1156 


DSTOR 


RAPID/ 30 00 DICTDBU Utility Store File 


1157 


TCODE 


Code File for Transact/3000 Compiler 


1158 


RCQDE 


Code File for Report/3000 Compiler 


1159 


I CODE 


Code File for Inform/ 3 000 Compiler 


1166 


MDIST 


HPDESK Distribution list 


1167 


MTEXT 


HPDESK Text 


1168 


MARPA 


ARPA Messages File 


1169 


MARPD 


ARPA Distribution List 


1170 


MCMND 


HPDESK Abbreviated Commands File 


1171 


MFRTM 


Reserved 


1172 




Reserved 


1173 


MEFT 


Reserved 


1174 


MCRPT 


Reserved 


1175 


MSERL 


Reserved 


1176 


VCSF 


Reserved 


1177 


TTYPE 


Terminal Type File 


1178 


TVFC 


Terminal Vertical Format Control File 


1192 


NCDNF 


Network Configuration File 


1193 


NTRAC 


Network Trace File 


1194 


NLDG 


Network Log File 


1195 


MIDAS 


Reserved 


1211 


ANODE 


Reserved 


1212 


I NODE 


Reserved 


1213 


INVRT 


Reserved 


1214 


EXCEP 


Reserved 


1215 


TAXON 


Reserved 


1216 


QUERF 


Reserved 


1217 


DDCDR 


Reserved 


1226 


VC 


VC File 


1227 


DIF 


DIF File 


1228 


LANGD 


Language Definition File 


1229 


CHARD 


Character Set Definition File 


1230 


MGCAT 


Formatted Application File 


1236 


B1AP 


Base Map Specification File 


1242 


BDATA 


Basic Data File 


1243 


BFDRM 


Basic Field Order File for VPLUS 


1244 


BSAVE 


Basic Saved Program File 


1245 


BCNFG 


Configuration File for Default Option Basic Program 


1258 


PFSTA 


Pathf low STATIC File 


1259 


PFDYN 


Pathflow DYNAMIC File 


1270 


RFDCA 


Revised Form DCA Document 


1271 


FFDCA 


Final Form DCA Document 


1272 


DIU 


Document Interchange Unit 


1273 


PDOC 


HPWORD/1 50 Document 


1401 


CWPTX 


Reserved 


1421 


MAP 


HPMAP/3000 Map Specification File 


1422 


GAL 


Reserved 


1425 


TTX 


Reserved 


3333 




Reserved 



Default is the unreserved file code of . 
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CONDITION CODES 

CCE Request granted. The file is open. 

CCG Not returned by this intrinsic. 

CCL Request denied. This may be because another process already has 

EXCLUSIVE or semi -exclusive access for this file, or an initial allocation 
of disc space cannot be made due to lack of disc space. The file number 
value returned by FDPEN is if the file is not opened successfully. The 
FCHECK intrinsic should be called for more details. 

ADDITIONAL DISCUSSION 

"File Device Relationships" and "How to Use Files" in Section IV. 
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FPARSE 

NO INTRINSIC NUMBER ASSIGNED 

Parses and validates file designators. (Available version G.02.00 or later.) 



BA IA LA 0-V 

FPARSE (string s result f items Rectors) ; 



FPARSE is called to ensure that the formal file designator is syntactically correct. It eliminates the 
need to write your own modules to parse and validate file names. FPARSE also eliminates any am- 
biguities about the correct syntax of the file designators and presents a more flexible and modular 
programming approach. It is recommended that all new programs use FPARSE to validate and parse 
file designators and that many of the existing application programs and subsystems enhance their code 
to use FPARSE. 



PARAMETERS 

stiping 

result 



byte array (required) 

A buffer which contains the file reference string to be parsed. The string 
can be delimited by any nonalphanumeric character except a slash (/), 
period (.), or colon (:). 

integer array (required) 

A two- word array. The first 16 -bit word of the array will contain the 
value indicating the result of the parse. If the value is positive, the file 
string is syntactically correct and the value indicates the type of file 
reference being made. The second word is reserved for future use. The 
following values are valid : 

- Regular file designator. 

1 - Backreference (" *" is the first character in string). 

2 - System file ("$" is the first character in string). 

If negative , it is one of the following error codes , indicating a syntax error 
in the file reference : 

Error# Meaning 

-1 Bad item values. 

-2 Parameter bounds violation . 

- 3 Illegal delimiter ; misuse of " . " "/ " or " : " . 

-4 User specified only one of items or vectors array. 

-5 Illegal item value in items array. 
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Error# Meaning 

-6 Item list not terminated by the terminator. 

-7 Undefined system file. 

-8 Lock word disallowed in backreferenced (*) file. 

-9 NS/3000 not present, but user specified envid. 

- 1 1 First character of the file name not alpha . 

-102 File name expected in the string. 

- 1 03 File name identifier too long. 

- 104 First character of lockword not alpha. 

-105 Lockword expected in the string. 

- 1 06 Lockword identifier too long . 

- 1 07 First character of the group name not alpha . 

- 1 08 Group name expected in the string. 

- 1 09 Group name identifier too long . 

- 1 1 First character of the account name not alpha. 

- 1 1 1 Account name expected in the string. 

■;».. 

- 1 1 2 Account name identifier too long . 

- 1 1 3 First character of envidname not alpha. 

- 1 1 4 The envidname expected in the string . 

- 1 1 5 Identifier for envidname too long . 

System-defined designators, i.e. file names starting with "$", are part of 
the file designator extension ; a file name starting with " : " is not part of 
the file designator extension and is considered an illegal delimiter . 

The default designator numbers for system files as defined for FOPEN /op- 
tion are : 

- Filename. 

1 - $STDLIST. 

2 - $NEWPASS. 

3 - $0LDPASS. 

4 - $STDIN. 

5 - SSTDINX. 

6 - $NULL. 
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items 



vectors 



In case of an error the first element of the vectors array returns the byte 
offset of the invalid item in string. The second word will be zero. 

There may be up to 3 identifiers separated by a period (.) in an envidname. 
Therefore, each of the errors, - 1 1 3 through -115, may be referring to one 
of the 3 identifiers. The error pointer will point to the location of the 
error . 

If the NS/3000 subsystem is not installed on the system, FPARSE will 
return error code -9 for file designators with envid after the file name. 
This error implies that everything else, up to the point where envid was 
detected, is valid. However, FPARSE will not return a parsed vectors 
array . 

logical array (optional) 

This array contains the item code, one-per-word, categorizing to what the 

corresponding vectors array should point : 

- End of item list in array. 

1 - File name. 

2 - Lock word. 

3 - Group name. 

4 - Account name. 

5 - NS/3000 envid name. 

double array (optional) 

An array which contains the vector element, one per double -word, for the 
requested items. The first word will contain the byte offset, from the base 
of the string array to the start of the item name, and the second word will 
contain the length. A length of zero will indicate that the item was not 
specified in the string array. There will be a one-to-one mapping with the 
items array, i.e. one items array word to one vectors array double -word. 
For Item , which terminates the items list , the corresponding entry in the 
vectors array will contain the total length of the file designator string in 
the second word and the first word will contain the default designator type 
(as in bits (10:3) of the FOPEN f options) if the result parameter indicates 
a system file. 



CONDITION CODES 

The condition code remains unchanged . 

ADDITIONAL DISCUSSION 

"Parsing and Validating File Designators" in Section IV. 
NS/3000 User/Programmer Reference Manual (32344-90001 ). 
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FPOINT 

INTRINSIC NUMBER 6 



Sets the logical record point for a disc file. 

SYNTAX 



IV DV 
FPD I NT tfileimm 3 ipecnum) ; 



The FPD I NT intrinsic sets the logical record pointer for a disc file (except serial disc) containing fixed - 
length or undefined -length records, to any logical record. When the next FREADor FWRITE request is 
issued for the file, this record will be the one read or written. 

PARAMETERS 

fiXerwm integer by value (required) 

A word supplying the file number of the file in which the pointer is to be 
set. 

recnum double by value (required) 

A positive double integer representing the relative logical record (or block 
number for a NOBUF file) at which the logical record pointer is to be posi- 
tioned. The number of the first first logical record is zero. 

On disc files, the end -of -file indicator is the file limit. 

CONDITION CODES 

CCE Request granted. 

CCG Request denied. The logical record pointer position is unchanged. 

Positioning was requested at a point beyond the file limit. 

CCL Request denied. The logical record point position is unchanged because of 

one of the following : 

• The recnum was <0. 

o Invalid filenum parameter. 

• Input/output is pending on a NOWAIT request. 

• The file is spooled or is not a direct -access disc file. 

• The file does not contain fixed -length or undefined -length records. 

• Not allowed with append access. 
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SPECIAL CONSIDERATIONS 

Split -stack calls permitted. 
Not applicable to message files. 

ADDITIONAL DISCUSSION 

MPE File System Reference Manual (30000-90236). 
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FREAD 

INTRINSIC NUMBER 2 



Reads a logical record or portion of a record from a file to the user's stack. 

SYNTAX 




The FREAD intrinsic reads a logical record , or a portion of such a record , from a file on any device to 
the user's stack. The record read is determined by the current position of the record pointer. 

When the logical end -of -data is encountered during reading, CCG is returned to the user process. On 
magnetic tape, the end -of -data can be denoted by a physical indicator such as a tape mark. When a 
file is read that spans more than one volume of labeled magnetic tape , the user program is suspended 
until the operator has completed mounting the next tape. CCG is not returned when end-of-tape is 
encountered. On disc, the end-of-data occurs when attempting to read beyond the last logical record 
of the file. In this case, CCG is returned and no record is read. If the file is embedded in an input 
source containing MPE commands, the end-of-data is indicated when an :EOD command is encoun- 
tered, but the :EDD command itself is not returned to the user. The end-of-data is indicated by a 
hardware end-of-file, including :EDF:; on $STDIN by any record beginning with a colon; or on 
SSTDINX by :EDD. In addition, on the standard input device for a job, as opposed to a session, : JOB, 
:E0J, or :DATA indicate end-of-data. 

When a message file is empty and there are no writers , the process will wait if there is an FCONTROL 
45 in effect. It will also wait if this is the first FREAD after the reader's FDPEN. Otherwise CCG is 
returned. If an FREAD is issued against a message file, and an FCONTRDL 46 is in effect, the writer's 
ID and the record type code are appended to the beginning of the record. 

When an old file containing carriage -control characters supplied through the control parameter of the 
FWRITE intrinsic is read, and the carriage control f option parameter of the FDPEN intrinsic, or the 
CCTL parameter of the :FILE command is specified, the carriage control byte is read as follows: 



CARRIAGE 
CONTROL 
BffE- 



DATA READ 



FUNCTIONAL RETURN 

Igth integer (optional) 

An integer value showing the length of the information transferred . If the 
tcount parameter in the FREAD call is positive, the positive value returned 
represents a word count; if the tcount parametei is negative, the positive 
value returned represents a byte count. FREAD always returns zero if 
NOW AIT I/O is specified . In this case , the actual record length is returned 
in the tcount parameter of the IOWA IT intrinsic. 

PARAMETERS 

filenum integer by value (required) 

A word supplying the file number of the file to be read. 

1 135 



target logical array (required) 

An array to which the record is to be transferred. This array should be 
large enough to hold all of the information to be transferred. 

tcount integer by value (required) 

An integer specifying the number of words or bytes to be transferred. If 
this value is positive, it signifies the length in words; if it is negative, it 
signifies the length in bytes; if it is zero, no transfer occurs. If tcount is 
less than the size of the record , only the first count words or bytes are read 
from the record. 

If tcount is larger than the size of the logical record, and the multirecord 
aoption was not specified in FDPEN, transfer is limited to the length of the 
logical record. If the multirecord aoption was specified in FOPEN, transfer 
continues until either tcount is satisfied or the end -of -data is encountered, 
and each transfer will begin at the start of the next physical record (block). 
Any data remaining in the last physical record read will be inaccessible. 

CONDITION CODES 

CCE The information was read . 

CCG The logical end-of-data was encountered during reading. When reading a 

labeled magnetic tape file that spans more than one volume, CCG is not 
returned when end -of -tape (EOT) is encountered. Instead, CCG is return- 
ed at actual end-of-file, with a transmission log of if an attempt is made 
to read past end-of-file. 

CCL The information was not read because an error occurred, a terminal read 

was terminated by a special character or time-out interval as specified in 
the FCONTROL intrinsic, or a tape error was recovered and the FSETMDDE 
option was enabled . 



NOTE 



The condition codes should be checked both in normal I/O and 
in NOW AIT I/O. 



SPECIAL CONSIDERATION 

Split -stack calls permitted. 

ADDITIONAL DISCUSSION 

"Using FREAD and FWRITE with $STDIN and SSTDLIST" in Section IV. 
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FREADBACKWARD 

NO INTRINSIC NUMBER ASSIGNED 



Reads a logical record backward from the current record pointer. Data is presented to the user as if 
read forward . 

SYNTAX 



I IV LA IV 

lgth:=FREmBbCKWARDCfUenum,target, tcount)-, 



The FREADBACKWARD intrinsic reads a logical record from a tape to the user's stack. The record read 
is determined by the current position of the record pointer. This intrinsic permits access to the "Read 
Reverse" capability of the HP -IB magnetic tape drives, and can be used to recover tape errors when 
handling I/O management and data recovery routines . 

Presently two substantial restrictions are associated with the use of this intrinsic: 

1 . It may only be used with magnetic tape drives on HP-IB Systems. 

2. The magnetic tape must be accessed NOBUF. 



FUNCTIONAL RETURN 



Igth 



integer (optional) 

An integer value showing the length of the information transferred. If the 
tcount parameter in the FREADBACKWARD call was positive, the positive 
value returned represents a word count; if the tcount parameter was nega- 
tive, the positive value returned represents a byte count. FREADBACKWARD 
always returns zero if NO WAIT I/O is specified. In this case, the actual 
record length is returned in the tcount parameter of the I OHA IT intrinsic. 



PARAMETERS 

filenum 
tcupget 

tcount 



integer by value (required) 

A word supplying the file number of the file to be read. 

logical array (required) 

An array to which the record is to be transferred. This array should be 

large enough to hold all of the information to be transferred. 

integer by value (required) 

An integer specifying the number of words or bytes to be transferred. If 
this value is positive, it signifies the length in words; a negative value sig- 
nifies the lengths in bytes; and zero means no transfer occurs. When tcount 
is less than the size of the record , only the first tcount words or bytes are 
read from the record . 
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If tcount is larger than the size of the logical record , and the multirecord 
aoption was not specified in FOPEN, transfer is limited to the length of the 
logical record. When the multirecord aoption was specified in FOPEN, 
transfer continues until either tcount is satisfied, or the beginning -of -data 
is encountered, and the transfer will begin at the end of the next physical 
record (block) . Any data remaining in the last physical record read will be 
inaccessible . 

CONDITION CODES 

CCE The information was read. 

CCG The logical beginning -of -data was encountered during reading. When 

reading a labeled magnetic tape file that spans more than one volume, CCG 
is not returned when beginning-of-tape (BOT) is encountered. Instead, 
CCG is returned at actual beginning of file, with transmission log of if 
an attempt is made to read past beginning of file. 

CCL The information was not read because a tape error occurred , or a tape error 

was recovered, and the FSETMODE option was enabled. 



NOTE 



The condition code should be checked both in normal I/O and in 
NOW AIT I/O. 



SPECIAL CONSIDERATIONS 

Split-stack calls permitted. 

ADDITIONAL DISCUSSION 

MPE File System Reference Manual (30000-90236). 
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FREADDIR 

INTRINSIC NUMBER 7 



Reads a specific logical record or portion of a record from a direct-access disc file to the user's data 
stack. 

SYNTAX 



IV LA IV DV 

FREADD I R (filenum,target , tcount t recnum'> ; 



The FREADDIR intrinsic reads a specific logical record, or a portion of such a record, from a disc file 
to the user's data stack. This intrinsic differs from the FREAD intrinsic in that the FREAD intrinsic 
reads only the record already pointed to by the logical record pointer. The FREADDIR intrinsic may 
be issued only for direct-access disc files composed of fixed-length records. If RIO access is used, 
FREADDIR will input the specified logical record. If the record is inactive, the contents of the inac- 
tive record will be transmitted and a CCE will be returned. In this case there is no indication 
whether the block contains some inactive records. (FCHECK returns a nonzero error number to distin- 
guish active and inactive records. If a RIO file is accessed using the nonRIO method, (NOBUF) 
FREADDIR will input the specified block.) 

After the FREADDIR intrinsic is executed, the logical record pointer is set to the beginning of the next 
logical record, or the first logical record of the next block for NOBUF files. 

It is possible to skip portions of records inadvertently if the multirecord aoption of FOPEN is set and 
tcount parameter specified is greater than one logical record. For example, if you read all of record 
1 1 and half of record 12 in a file, the logical record pointer is set to the beginning of record 1 3 after 
the FREADDIR intrinsic executes. Thus the second half of record 1 2 is skipped. 



PARAMETERS 

filenum 

target 
tcount 



integer by value (required) 

A word supplying the file number of the file to be read. 

logical array (required) 

An array to which the record is to be transferred. This array should be 

large enough to hold all of the information to be transferred. 

integer by value (required) 

An integer specifying the number of words or bytes to be transferred. If 
this value is positive, it signifies words; a negative value bytes; and zero 
signifies that no transfer occurs. If tcount is less than the size of the 
record, only the first tcount words or bytes are read from the record. 

If tcount is larger than the size of the logical record and the multirecord 
aoption was not specified in FOPEN, the transfer is limited to the length of 
the logical record. If the multirecord aoption was specified in FOPEN, the 
remaining words or bytes specified in tcount are read from succeeding 
records. 
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recnum double by value (required) 

A double -word integer indicating the relative number, in the file of the 
logical record or block number for NOBUF files to be read. The first 
record is indicated by "OD" (double -word zero in SPL notation). 

CONDITION CODES 

CCE The information was read . 

CCG End-of-file was encountered. 

CCL The information was not read because an error occurred. 

SPECIAL CONSIDERATIONS 

Split -stack calls permitted. 
Not applicable to message files. 

ADDITIONAL DISCUSSION 

MPE File System Reference Manual (30000-90236). 
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FREADLABEL 

INTRINSIC NUMBER 19 



Reads a user file label . 

SYNTAX 



O-V IV LA IV IV 

FREf\T)LtoEEL(filentmt 3 txzrget>tccnmt } labelid~)i 



The FREADLABEL intrinsic reads a user -defined label from a disc file or magnetic tape file. Once a 
disc file has been opened, user labels may be read from or written to in any order at any time, regard- 
less of the opener's access to the rest of the file. A disc file can have up to 254 128-word user labels. 
A magnetic tape file, if labeled at all, must be labeled with an ANSI -standard or IBM -standard label. 
MPE automatically skips over any unread user labels when the first FREAD intrinsic call is issued for 
files. Therefore for labeled tape files, the FREADLABEL intrinsic should be called immediately after 
the FDPEN intrinsic has opened the file. The user-defined label must be 40 words in length to con- 
form to the length of the ANSI or IBM -standard label. 



PARAMETERS 

fil email 
target 

tcount 



labelid 



integer by value (required) 

A word supplying the file number of the file whose label is to be read. 

logical array (required) 

An array in the stack to which the label is to be transferred. This array 

should be large enough to hold the number of words specified by tcount. 

integer by value (optional) 

An integer specifying the number of words to be transferred from the 

label. The limit is 128 words. 

Default: 128 words. 

integer by value (optional) 

An integer specifying the label number. For labeled tapes labelid is ig- 
nored . The next sequential label is read . 

Default: Zero is assigned. 



CONDITION CODES 

CCE The label was read. 

CCG The intrinsic referenced a label beyond the label written on the file. 

CCL The label was not read because an error occurred. 
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SPECIAL CONSIDERATIONS 

Split-stack calls permitted. 

ADDITIONAL DISCUSSION 

MPE File System Reference Manual (30000-90236). 
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FREADSEEK 

INTRINSIC NUMBER 12 



Moves a record from a disc file to a buffer in anticipation of a FREADD I R intrinsic call. 

SYNTAX 



IV DV 

FREADSEEK ifiXertum s recram) ; 



Direct access of disc files can be enhanced by issuing the FREADSEEK intrinsic call. This call is used 
when the need for a certain record is known before its transfer to the user's stack by a FREADD I R call 
is actually required. The FREADSEEK intrinsic directs MPE to move the record from disc into a buffer 
in anticipation of the FREADD I R call, which subsequently moves the record directly to the stack. 

The FREADSEEK intrinsic call can be issued only for direct-access files for which input/output buffer- 
ing and fixed or undefined-length records are in effect. 

PARAMETERS 

filenum integer by value (required) 

A word supplying the file number of the file to be read. 

recnum double by value (required) 

A double-word integer in SPL notation indicating the relative number of 
the logical record to be read. The first record is indicated by "OD" 
(double-word zero in SPL notation). 

CONDITION CODES 

CCE Request granted. 

CCG A logical end-of-file indication was encountered. 

CCL Request denied because an error occurred. 

SPECIAL CONSIDERATIONS 

Split-stack calls permitted. 
Not applicable to message files . 

ADDITIONAL DISCUSSION 

MPE File System Reference Manual (30000-90236). 
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INTRINSIC NUMBER 131 
Releases an extra data segment. 

SYNTAX 



LV LV 
FREEDSEGCifKfea;,-wD ; 



A process can release an extra data segment assigned to it by using the FREEDSEG intrinsic. If this is a 
private data segment, or if it is a sharable (nonprivate) segment not currently assigned to any other 
process in the job/session, the segment is deleted from the entire job/session. If it is a sharable seg- 
ment which is currently assigned to any other process, it is deleted from the calling process but con- 
tinues to exist in the job/session . 

PARAMETERS 

index logical by value (required) 

A word containing the logical index assigned to the data segment, obtained 
from the GETDSEG intrinsic call. 

id logical by value (required) 

The identity assigned to the segment. If none is assigned, enter a zero. 

CONDITION CODES 

CCE Request granted. The data segment is deleted from the job/session . 

CCG Request granted. The data segment is deleted from the calling process but 

continues to exist in the job/session because it is being shared by another 
process . 

CCL Request denied. Either the index is invalid or index and id do not specify 

the same extra data segment. 

SPECIAL CONSIDERATIONS 

Data Segment Management (DS) capability required. 

ADDITIONAL DISCUSSION 

The GETDSEG intrinsic in this section, and "Deleting an Extra Data Segment" in Section III. 
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FREELOCRIN 

INTRINSIC NUMBER 31 



Frees all local Resource Identification Numbers (RINs) from allocation to a job. 

SYNTAX 



FREELOCRIN; 



The FREELOCRIN intrinsic frees all local Resource Identification Numbers (RINs) currently reserved 
from your job. 

If the GETLOCRIN intrinsic has been called by a process, the FREELOCRIN intrinsic must be called 
before GETLOCRIN can be called successfully a second time. 

CONDITION CODES 

CCE Request granted. 

CCG Request denied because no RINs are currently reserved for the job. 

CCL Request denied because at least one RIN is currently locked by a process. 

ADDITIONAL DISCUSSION 

"Resource Management " in Section III . 
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FRELATE 

INTRINSIC NUMBER 18 



Determines whether a file pair is interactive , duplicative , or both interactive and duplicative . 

SYNTAX 



L IV IV 

intordup : -FRELfiiTECinfilenum y listfi,lenum') ; 



A devicefile is interactive if it requires human intervention for all input operations. This quality is 
necessary to establish the person/machine dialog required to support a session. A devicefile is duplica- 
tive if all input operations are echoed to a corresponding display without intervention by the operat- 
ing system software. 

You can determine whether a pair of files is interactive, duplicative, or both interactive and duplica- 
tive through the FRELATE intrinsic call. The interactive/duplicative attributes of a file pair do not 
change between the time the files are opened and the time they are closed . 

The FRELATE intrinsic applies to files on all devices. 



FUNCTIONAL RETURN 



intordup 



logical (optional) 

A word indicating whether the two files referenced are interactive and/or 

duplicative . It contains two bits of importance : 

Bit (15:1) 

=0 The infilenum and listfilenum do not form an interactive pair. 

= 1 The infilenum and listfilenum form an interactive pair. 

Bit (0:1) 

=0 The infilenum and listfilenum do not form a duplicative pair. 

= 1 The infilenum and listfilenum form a duplicative pair . 



PARAMETERS 

infilenum 

listfilenum 



integer by value (required) 

A word supplying the file number of the input file. 

integer by value (required) 

A word supplying the file number of the list file. 
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CONDITION CODES 

CCE Request granted. 

CCG Request denied because infilenum and/or listfilenum corresponds to $NULL. 

$NULL is considered to be a logical file which contains no data. No data 
can be read from this file and all data written to it is discarded. The in- 
filenum and listfilenum functions, therefore, are illogical for the $NULL 
file. Interactive or duplicative functions do not apply. 

CCL Request denied because an error occurred. 

SPECIAL CONSIDERATIONS 

Split-stack calls permitted. 

ADDITIONAL DISCUSSION 

MPE File System Reference Manual (30000-90236). 
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FRENAME 

INTRINSIC NUMBER 17 
Renames a disc file . 

SYNTAX 



IV BA 

FRENAME Cfileman s neisfilereference ) ; 



The FRENAME intrinsic changes the actual designator (including lock word, if any) of an open disc file. 
The home volume set of newfilereference must be the same as that of the file being renamed. 
(Volume sets cannot be spanned when renaming files.) 

The file to be renamed must be either : 

• A new file. 

• An existing file, opened for EXCLUSIVE access, for which you have WRITE access (specified by 
the security provisions of the file). If the file is a permanent file, you must be the creator. 



PARAMETERS 

filenum 
neafilereference 



integer by value (required) 

A word supplying the file number of the file to be renamed. 

byte array (required) 

Contains an ASCII string specifying the new name of the file. The maxi- 
mum number of characters allowed in the string is 36. The format of new- 
filereference is: 

filename/lockword . group . account 

filename The new file name for the file. (Required in 
newfilereference . ) 

lockword A lockword for the new file name. (Optional parameter of 
newfilereference . ) If you wish to keep or add a lockword to 
the file, you must enter the lockword parameter in the 
ASCII string. If this part of newfilereference is not 
specified, the new file named will not have a lockword as- 
sociated with it. 

group The group where the file is to reside. (Optional parameter 

of newfilereference.) If no group is specified, the file will 
reside in the group it was assigned before the FRENAME in- 
trinsic call. 

account The account name where the file is to reside. (Optional pa- 

rameter of newfilereference .) The account to which the file 
is currently assigned must be used. If other than the cur- 
rent account name is specified, the CCL error condition is 
returned and the file retains its old name. 
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The ASCII string contained in newfilereferen.ee must begin with a letter; 
can contain up to eight alphanumeric characters for each of the filename, 
lockword, group, and account fields. The string must end with a nonal- 
phanumeric character including a blank, but not a slash (/) or a period (.) 
since these are used as field delimiters within the string. 



CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied because an error occurred . 

ADDITIONAL DISCUSSION 

None. 
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FSETMODE 

INTRINSIC NUMBER 14 

Activates or deactivates the file access modes. 

SYNTAX 



IV LV 

FSETWI)Etfileman,modeflags ) ; 



The FSETMODE intrinsic activates or deactivates the following access mode options: automatic error 
recovery , terminal control by the user , and critical output verification . 

The access mode established by the FSETMODE intrinsic remains in effect until another FSETMODE call 
is issued or until the file is closed. The FSETMODE intrinsic applies to files on all devices. 

The FSETMODE intrinsic allows access to the MPE global Serial Write Queue and BLOCKONWRITE pa- 
rameter on a file-by -file basis. By enabling the Serial Write Queue on a file, all write requests are 
guaranteed to be performed in the order issued. This preserves integrity while allowing the perfor- 
mance benefits of uninterrupted process execution (BL0CKONWRITE=NO). This option may affect total 
system performance; contact your Hewlett-Packard SE before enabling it. The Serial Write Queue is 
globally disabled if the : CACHECONTROL BLOCKONWRITE=YES was specified, since this causes all 
processes on the system to wait for the physical disc I/O to complete. 

BLOCKONWRITE management can also be controlled on a file-by-file basis with the FSETMODE intrin- 
sic. If BLOCKONWRITE is locally enabled, the user's application will not be notified of a disc write 
completion until the physical write operation has completed. Therefore, the BLOCKDNWR I TE option 
guarantees commitment of the transaction to disc prior to completion notification to the user's ap- 
plication. The FSETMODE setting of an individual file will be overridden if the : CACHECONTROL 
BLOCKONWRITE* YES is specified. 

A combination of these two options in FSETMODE provides complete integrity and transaction com- 
mitment notification with disc caching with minimal performance impact. Many disc writes can be 
performed with BLOCKDNWR I TE=N0, Series Write Queue enabled, and guarantee integrity. On the 
final disc write of a transaction, both localized BL0CK0NWRITE=YES and Serial Write Queue enabled 
can be specified to provide both integrity and total transaction commitment notification . 

PARAMETERS 

fileman integer by value (required) 

A word supplying the file number of the file to which the call applies. 

modeftags logical by value (required) 

A 1 6 -bit value that denotes the access mode options in effect , as described 
below : 

Bit (15:1) - Serial Write Queue . This bit may be set as follows : 

=0 Disabled. Serial I/O is not guaranteed. 

= 1 Enabled. All physical I/O performed for this file will be guaranteed to 
be output to disc in the order in which the I/Os were sent. This bit is 
effective only on systems with disc caching enabled. With disc caching, 
it is possible for I/Os to be posted in a different order than sent . 
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Bit (14: 1) - BLOCKONWRITE. This bit has the following settings: 

=0 Disabled . Output is not verified . 

= 1 Enabled. All physical (block) output to the file is to be verified as 
physically complete (when full data buffers are posted) before control 
returns from a write intrinsic to the user's program. The user waits 
while the system is posting a full block, to the file. Note that this bit is 
effective only in buffered mode . 

Bit (13:1) - Terminal control by the user. 
This bit has the following settings : 

=0 MPE will automatically issue the carriage return and line feed for the 
terminal. This parameter is ignored if the device is not a terminal. 

= 1 Inhibit normal terminal control by the system. MPE will not issue an 
automatic carriage return and line feed at the completion of each ter- 
minal output line. 

Carriage return , line feed is not issued in the case where FREAD filenum , 
target, or tcount is satisfied {tcount characters are typed in). If [RETURN! is 
pressed , however , a carriage return is echoed but no line feed is sent . This 
also applies to the READ intrinsic. 

Bit (12:1) - Tape error recovery. 
This bit may be set as follows : 

=0 Tape error and report condition code CCE. 

= 1 Report recovered tape error by FREAD or FWRITE with condition code 
CCL and error number. 

The remaining bits (0: 1 2) are reserved for MPE and must be set to zero. 



CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied because an error occurred. 
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SPECIAL CONSIDERATIONS 

Split -stack calls permitted. 

ADDITIONAL DISCUSSION 

"Declaring Access-Mode Options" in Section IV. 

MPE File System Reference Manual (30000-90236). 

MPE V System Operation and Resource Management Reference Manual (32033-90005). 

Point-to-Point Workstation I/O Reference Manual (30000-90250). 
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FSPACE 

INTRINSIC NUMBER 5 



Moves a physical record pointer forward or backward on a tape or disc file . 

SYNTAX 



IV IV 

FSPACE <.filenum 3 dirSplacement ) ; 



You can space forward or backward on a fixed -length or undefined -length file by using the FSPACE 
intrinsic to reset the logical record pointer. The FSPACE intrinsic applies to files on disc and magnetic 
tape devices (including serial discs) only. On magnetic tape devices FSPACE spaces physical rather 
than logical records. 

The FSPACE intrinsic cannot be used with variable -length record files, message files, or with spooled 
files on disc. An attempt to use this intrinsic on such files results in CCL, and the logical record 
pointer is left at its current position. 

Refer to the MPE File System Reference Manual (30000-90236) for special considerations on mag- 
netic tape files. 



PARAMETERS 

filenum 
displacement 



integer by value (required) 

A word supplying the file number of the file on which spacing is to be 

done. 

integer by value (required) 

A signed integer indicating the number of logical records for buffered disc 
files, or blocks for NOBUF files and all tape files, to be spaced over, rela- 
tive to the current position of the logical record pointer. A positive value 
signifies forward spacing , a negative value signifies backward spacing . The 
maximum positive value is 32767, the maximum negative value is -32768. 
If RIO access is used, the displacement includes all records regardless of ac- 
tivity state (that is, active or deleted). Attempts to backspace beyond the 
beginning of the file will be ignored by the system. The logical record 
pointer will point to record (the first record) and no error codes will be 
returned . 
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CONDITION CODES 

CCE Request granted. 

CCG An end-of-file indicator was encountered during spacing. For disc files, 

this is the file limit, and the logical record pointer is not changed. For 
magnetic tape files, it is the end-of-file mark, and the logical record 
pointer points to the (logical) end-of-file. The magnetic tape, however, is 
positioned to one record past the file mark on the tape. For labeled tape 
the logical record pointer is at the file mark . 

CCL Request denied because an error occurred ; for example , the file resides on a 

device that prohibits spacing . Not allowed with APPEND access . 

SPECIAL CONSIDERATIONS 

Split -stack calls permitted. 

ADDITIONAL DISCUSSION 

MPE File System Reference Manual (30000-90236). 
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FUNLOCK 

INTRINSIC NUMBER 16 



Dynamically unlocks a file. 

SYNTAX 



IV 
FUNLDCKC/ilenam); 



The FUNLDCK intrinsic dynamically unlocks a file that has been locked with the FLOCK intrinsic. 

PARAMETERS 

fileman integer by value (required) 

A word supplying the file number of the file to be unlocked . 

CONDITION CODES 

CCE Request granted. 

CCG Request denied because the file had not been locked by the calling process. 

CCL Request denied because the file was not opened with the dynamic locking 

aoption of the FOPEN intrinsic, or the filenum parameter is invalid. 

SPECIAL CONSIDERATIONS 

Split-stack calls permitted. 

ADDITIONAL DISCUSSION 

MPE File System Reference Manual (30000-90236). 
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FUPDATE 

INTRINSIC NUMBER 4 

Updates (writes) a logical record in a disc file. 

SYNTAX 



IV LA IV 

FUPDATE (fileman, target , tcount ) ; 



The FUPDATE intrinsic updates a logical record in a disc file . This intrinsic affects the logical record 
(or block for NOBUF files) last referenced by any intrinsic call for the file named except for FPOINT 
which affects the record prior to the last record referenced. FUPDATE moves the specified informa- 
tion from the user's stack into this record. The file containing this record must have been opened 
with the update aoption specified in the FOPEN call, and must not have variable-length records. If 
RIO access is used, the modified record is set to the active state. 

FUPDATE is functionally equivalent to, but faster than, FSPACE(/iZenum,-1); followed by an 
FWR I TE to /iZenum. 

PARAMETERS 

filenum integer by value (required) 

A word supplying the file number of the file to be updated . 

target logical array (required) 

Contains the record to be written in the updating . 

tcount integer by value (required) 

An integer specifying the number of words or bytes to be written from the 
record. If this value is positive, it signifies words; a negative value sig- 
nifies bytes; and a zero indicates that no transfer occurs. To have all con- 
tents of a record written, tcount must be set at >=RECSIZE. 

CONDITION CODES 

CCE Request granted. 

CCG An end-of-file condition was encountered during updating. 

CCL Request denied because of an error , such as the file not residing on disc , or 

tcount exceeding the size of the block when multirecord mode is not in 
effect . 



2-156 



SPECIAL CONSIDERATIONS 

Split-stack calls permitted. 
Not applicable to message files. 

ADDITIONAL DISCUSSION 

MPE File System Reference Manual (30000-90236). 
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FWRITE 

INTRINSIC NUMBER 3 

Writes a logical or physical record or portion of a record from the user's stack to a file on any device. 

SYNTAX 



IV LA IV LV 

FWRITE Cfileman s tax>get ,tcount iCcmtrol ) ; 



The FWRITE intrinsic writes a logical or physical record, or a portion of such a record, from the user's 
stack to a file on any device . 

When information is written to a fixed -length record, and the NOBUF aoption was not specified in 
FDPEN, any unused portion of the record will be padded with binary zeros for a binary file or ASCII 
blanks for an ASCII file . 

When the FWRITE intrinsic is executed, the logical record pointer is set to the record immediately fol- 
lowing the record just written, or the first logical record in the next block for NOBUF files. If RIO 
access is used , the modified record is set to the active state . 

When an FWRITE call writes a record beyond the current logical end-of-file indicator, this indicator 
is advanced to a farther location ; however , this is only noted in the file label when the file is actually 
closed or when an extent is allocated. If the physical bounds of the file are reached, CCG is returned. 

If a magnetic tape or serial disc is unlabeled (as specified in the FOPEN intrinsic or :FILE command) 
and a user program attempts to write over or beyond the physical or simulated end-of-tape (EOT) 
marker, the FWRITE intrinsic returns CCL. The actual data has been written to the tape, and a call 
to FCHECK reveals a file error indicating end-of-tape. All writes to the tape after the EOT tape 
marker has been crossed transfer the data successfully but return CCL until the tape crosses the EOT 
marker again in the reverse direction (rewind or backspace). 

If a magnetic tape or serial disc is labeled (as specified in the FDPEN intrinsic or : FILE command), 
CCL is not returned when the tape passes the EOT marker. Attempts to write to the tape after the 
EOT marker is encountered cause end-of-volume (EOV) markers to be written. A message then is 
printed on the System Console requesting another volume (reel of tape) to be mounted. 

For message files and circular files this intrinsic logically appends the user's record to the end of the 
file. If circular file is full, the first block is deleted, the remaining blocks are logically shifted to the 
file's head, and the new record is appended to the end of the file. If a message file is full and there 
are no readers, the process will wait if there is an FCDNTROL 45 in effect. It will also wait if this the 
first FWRITE after the writer's FDPEN. Otherwise, CCG is returned. 

PARAMETERS 

filenum integer by value (required) 

A word supplying the file number of the file to be written on. 

target logical array (required) 

Contains the record to be written. 
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tcount 



integer by value (required) 

An integer specifying the number of words or bytes to be written to the 
record. If this value is positive, it signifies words; a negative value, bytes; 
and a zero indicates that no transfer occurs. If tcount is less than the rec- 
size parameter associated with the record, only the first tcount words or 
bytes are written . 

If tcount is larger than the logical record size and the NOBUF aoption is not 
specified in FDPEN, the FWRITE request is refused and CCL is returned. If 
NOBUF is specified, tcount may not exceed the physical record size unless 
the multirecord aoption is specified. 

If the multirecord aoption is specified in FDPEN, the excess words or bytes 
are written to succeeding physical records. For files for which carriage 
control is specified, the actual data transferred is limited to recsize minus 
one byte. 



control 



logical by value (required) 

A logical value representing a carriage control code, effective if the file is 
transferred to a line printer or terminal (including a spooled file whose ul- 
timate destination is a line printer or a terminal). This parameter is effec- 
tive only for files opened with carriage control specified. 



The options are : 

Print the full record transferred, using single spacing, 
maximum of 1 32 characters per printed line. 



This results in a 



1 Use the first character of the data written to satisfy space control, and 
suppress this character on the printed output. This results in a maxi- 
mum of 1 32 characters of data per printed line. Permissible control 
characters are shown in Table 2-5. 

Any octal code from Table 2-5 can be used to determine space control and 
print the full record transferred. This results in a maximum of 132 
characters per printed line. 

If the control parameter is not or 1, and tcount is 0, only the space con- 
trol is executed and no data is transferred. 

The effect of the FWRITE control parameter in combination with the FDPEN 
carriage control f opt ion (or overriding :FILE command CCTL/NOCCTL 
parameter) upon the data written is summarized in Figure 2-3. 

You determine whether the carriage control directive takes effect before 
printing (pre-space movement) or after printing (post-space movement), 
through the FCDNTROL intrinsic . 

For spooled files it is necessary to set the pre-space/post-space control and 
the auto/no auto page eject control using FWRITE instead of FCDNTRDL. 
You may use control codes %100 through %103 and %400 through %403 for 
this. If you specify one of the above controls with tcount = 0, no physical 
I/O will occur. 
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For non-spooled devicef iles , all of the Carriage Control Codes listed in 
Table 2- 5 may be used as the value of the param parameter in FCDNTROL 
(when controlcode = 1 ) , regardless of whether the file is opened with CCTL 
or NOCCTL. When the file is opened with CCTL, these carriage control 
codes may be used in either of the following ways via FWRITE: 

• As the value of the control parameter. 

• When control - 1 , as the first byte of the target array. 

The default carriage control code is post -spacing with automatic page eject. 
This applies to all Hewlett-Packard-supported subsystems except 
FORTRAN and COBOL which have prespacing with automatic page eject. 

CONDITION CODES 

CCE Request granted. 

CCG The physical bounds of the file prevented further writing; all disc extents 

are filled. 

CCL Request denied because an error occurred , such as tcount exceeding the size 

of the record in nonmultirecord mode; the FSETMODE option is enabled to 
signify recovered tape errors; or the end-of-tape marker was sensed. If 
the file is being written to a multi volume labeled magnetic tape set, CCL is 
not returned when the end-of-tape marker is sensed. Instead, end-of- 
volume labels are written, and a request is issued to mount the next 
volume . 

SPECIAL CONSIDERATIONS 

Split -stack calls permitted. 

ADDITIONAL DISCUSSION 

MPE File System Reference Manual (30000-90236). 
Point-to-Point Workstation I/O Reference Manual (30000-90250). 
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Table 2-5. Carriage Control Directives 



OCTAL CODE ASCII SYMBOL CARRIAGE ACTION 



%40 "" Single space (with or without automatic page eject). 

%53 "+" No space, return (next printing at column 1). This 

cannot be used more than once on the HP 2608A/S 
without losing data. 

5*55 "-" Triple space (with or without automatic page eject).* 

%60 "0" Double space (with or without automatic page eject).* 

%6 * "1 " Conditional page eject (form feed) is performed by the 

software. If the printer is not already at the top of 
the form, a page eject is performed. Ignored if: 

Post -space mode: The current request has a transfer 
count of and the previous request was FDPEN, 
FCLOSE, or FWRITE which specified a carriage control 
directive of %6 1 . 

Pre-space mode: Both the current request and the 
previous request have transfer counts of 0, and the 
current request and previous request are any combina- 
tion of FOPEN, FCLOSE, or FWRITE specifying a car- 
riage control of %6 1 . 

%62 Skip to one line before top of form. This specification 

is valid only for the HP 2608S and 2563A printers. 

%63 A conditional page eject form (form feed) is perform- 

ed by the printer. If the printer is not already at the 
top of form, perform a page eject. This specification 
is valid only for the HP 2608S and 2563A printers. 

Kin* Space nn lines (no automatic page eject); nn is any oc- 

tal number from through 77. 

%300 - %313 Select VFC Channel 1 - 12 (HP 2613, 2617, 2618, 

2619). 

%300 - %317 Select VFC Channel 1 - 16 (HP 2608A/S). 



*Note : If these codes are selected with automatic page eject in effect (by default or following an octal 
code of %102 or %402), the resulting skip is to a location absolute to the page. A code of %60 is 
replaced by %303, and a code of %55 is replaced by % 3 04. Thus, the resulting skip may be less than 
two or three lines , respectively . 

If automatic page eject is not in effect, a true double or triple space results, but the perforation be- 
tween pages is not automatically skipped. For the HP 2608S and 2563A, if auto-eject and feature 
mode are in effect, a code of %60 will be replaced by two codes of % 3 02, and a code of %55 is replaced 
by three codes of %302. The resulting skip will be double or triple space with auto -eject, 
respectively . 
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Table 2-5. Carriage Control Directives (Continued) 



OCTAL CODE ASCII SYMBOL 


CARRIAGE ACTION 




NOTE: 




Channel assignments shown below are the Hewlett-Packard 




standard defaults. 


%300 


Skip to top of form (page eject). 


%301 


Skip to bottom of form. 


%302 


Single spacing with automatic page eject . 


%303 


Skip to next odd line with automatic page eject. 


%304 


Skip to next third line with automatic page eject. 


%305 


Skip to next 1/2 page. 


%306 


Skip to next 1/4 page. 


%307 


Skip to next 1/6 page. 


%310 


Skip to bottom of form . 


%311 


User option (HP 2613/17/18/19), skip to one line before 




bottom of form (HP 2608A/S). 


%312 


User option (HP 2613/17/18/19), skip to one line before 




top of form (HP 2608A/S). 


%313 


User option (HP 2613/17/18/19), skip to top of form (HP 




2608A). 


%314 


Skip to next seventh line with automatic page eject . 


%315 


Skip to next sixth line with automatic page eject . 


%316 


Skip to next fifth line with automatic page eject. 


%317 


Skip to next fourth line with automatic page eject. 


%320 


No space, no return (next printing physically follows this). 


%2 - %37 




°/Al -%52 




%54 




%56-%57 


Same as %40. 


%62-%77 




%104-%177 




%310-%317(HP 2607) 




%314-%317 (HP 2613/17/18/19) 




%321-%377 




%400or%100 


Sets post -space movement option; this first prints, then 




spaces. If previous option was pre -space movement, the 




driver outputs a line with a skip to VFC Channel 3 (auto- 




matic page eject in effect) or a one line advance (equivalent 




to an octal code of %201 without automatic page eject) to 




clear the buffer . 


%401 or%101 


Sets pre-space movement option; this first spaces, then 




prints . 


%402or%102 


Sets single-space option, with automatic page eject (60 lines 




per page). 


%403or%103 


Sets single-space option, without automatic page eject (66 




lines per page). 
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EFFECT ON DATA OUTPUT 
Figure 2-3. Carriage Control Summary 
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FWRITEDIR 

INTRINSIC NUMBER 8 

Writes a specific logical record from the user's stack to a disc file . 

SYNTAX 



IV LA IV DV 

FWR I TED I R (.filenum s target 3 tcount ,x>ecnum) ; 



The FWRITEDIR intrinsic writes a specific logical record (or physical record if NOBUF is specified), or 
a portion of such a record, from the user's stack to a disc file. This intrinsic differs from the FWRITE 
intrinsic in that the FWR I TE intrinsic writes only the record pointed to by the logical record pointer. 
The FWRITEDIR intrinsic may be used only for disc files composed of fixed- or undefined -length 
records. 

When information is written to a fixed-length record and NOBUF was not specified in the FDPEN call 
that opened the file , any unused portion of the record will be padded with binary zeros for a binary 
file, or ASCII blanks for an ASCII file. 

When the FWRITEDIR intrinsic is executed, the logical record pointer is set to the record immediately 
following the record just written, or the first logical record of the next block for NOBUF files. 

If RIO access is used, the modified record is set to the active state. 

When an FWRITEDIR call writes a record beyond the current logical end-of-file indicator, the in- 
dicator is advanced to a farther location . This can result in the creation of dummy records to pad the 
records between the previous end-of-file and the newly written record. These dummy records are 
filled with binary zeros for a binary file , or with ASCII blanks for an ASCII file when the new record 
is in the same extent . 

When the physical bounds of the file prevent further writing , because all allowable extents are filled , 
the end-of-file condition (CCG) is returned to the user's program. 

PARAMETERS 

filenum integer by value (required) 

A word supplying the file number of the file to be written on . 

target logical array (required) 

Contains the record to be written. This array should be large enough to 
hold all of the information to be transferred . 

tcount integer by value (required) 

An integer specifying the number of words or bytes to be written to the 
record. If this value is positive, it signifies words; a negative value, bytes; 
and a zero indicates that no transfer occurs. If tcount is less than the rec- 
size parameter associated with the record, and NOBUF was specified, only 
the first tcount words or bytes are written. 
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If tcount is larger than the size of the logical record and the NOBUF aop- 
tion was not specified in FDPEN, the transfer is limited to the length of the 
logical record. If NOBUF was specified and if tcount is larger than the size 
of the physical record, the transfer is limited to the length of the physical 
record if the multirecord aoption was not specified. If the multirecord aop- 
tion was specified in FDPEN, the remaining words or bytes are written to 
succeeding physical records up to the file limit. 

recnum double by value (required} 

A double integer indicating the relative number of the logical record, or 
block number for NOBUF files, to be written. The first record is indicated 
by zero. 

CONDITION CODES 

CCE Request granted. 

CCG The physical end -of -file was encountered. 

CCL Request denied because an error occurred. 

SPECIAL CONSIDERATIONS 

Split-stack calls permitted. 
Not applicable to message files. 

ADDITIONAL DISCUSSION 

MPE File System Reference Manual (30000-90236). 
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FWRITELABEL 

INTRINSIC NUMBER 20 
Writes a user file label. 

SYNTAX 



O-V IV LA IV IV 

FWRITELABEL if xlerwm ^target ,tcount i labelid'> ; 



The FWRITELABEL intrinsic writes a user-defined label onto a disc file or labeled magnetic tape file 
that is labeled with an ANSI -standard or IBM -standard label. This intrinsic overwrites old user 
labels. Once a disc file has been opened, user labels may be read from or written to regardless of the 
user's access to the rest of the file. If the file is on labeled magnetic tape, the user-defined label must 
be 40 words in length to conform to the length of the ANSI or IBM-standard label. 

PARAMETERS 

filenum integer by value (required) 

A word supplying the file number of the file to be labeled. 

target logical array (required) 

Contains the label to be written . If the file is a labeled magnetic tape file , 
this label must be 40 words in length. 

tcoimt integer by value (optional) 

The number of words to be transferred from the array. The default is 128 
words . 

labelid integer by value (optional) 

The number of the label to be written. The first label is 0. This parameter 
is ignored for labeled tapes. The next sequential tape label is written . Zero 
is assigned as the default. 

CONDITION CODES 

CCE Request granted. 

CCG Request denied because the calling process attempted to write a label 

beyond the limit specified in FOPEN when the file was opened. 

CCL Request denied because an error occurred. 

SPECIAL CONSIDERATIONS 

Split -stack calls permitted. 

ADDITIONAL DISCUSSION 

MPE File System Reference Manual (30000-90236). 
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GENMESSAGE 

NO INTRINSIC NUMBER ASSIGNED 



Accesses the MPE message system. 

SYNTAX 



I O-V IV IV IV BA IV LV 

msglen : =GENMESSAGE ifilentm a s&tnum i Tasgnum 3 buff > buff size ^parmzsk 3 

LV LV LV LV LV IV I 

pavaml , paramZ } param3 , param4 , paramS , msgdest , errnum ) ; 



The GENMESSAGE intrinsic accesses the MPE message system. A message number is passed by 
GENMESSAGE to the message system. The message system gets the message from a message catalog 
(opened by the calling program), inserts parameters supplied by GENMESSAGE into the message, then 
routes the message to $STDLIST, to a file, or returns the message to the calling program. (If msgdest 
is specified, the message is routed to a file; if buff is specified, the message is returned; if both 
msgdest and buff are specified, the message is routed to a file and returned.) 



NOTE 



The catalog file must be opened with f opt ions "old, 
permanent, ASCII" (f opt ions 5), and aoptions "NOBUF 
and MULTIrecord access" (aoptions %420). 



FUNCTIONAL RETURN 



msglen 



integer (optional) 

The length of the message is returned (in bytes). 



PARAMETERS 

fiZenum 

setnum 

msgrwm 
buff 



integer by value (required) 

A word supplying the file number of the message catalog . 

integer by value (required) 

A positive integer no greater than 62 specifying the message set number 

within the catalog. 

integer by value (required) 

A positive integer , specifying the message number within the message set . 

byte array (optional) 

A byte array to which the assembled message is returned. 

Default: Message is not returned to calling program. 
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buffsize 



parmask 



parcanl 



paramZ 



paramZ 



integer by value (optional) 

When buff is specified, buffsize is the size, in bytes, of the buffer. When 
buff is not specified, buffsize is the length, in bytes, of the records written 
to the destination file. 

Default: 72 bytes. 

logical by value (optional) 

A 16 -bit logical mask indicating parameter types for paraml , param2, 

par am 3, param4, and paramS. The bit settings are as follows: 

Bits (13:3) - Defines paramS type. 

=000 Parameter is a string, terminated by an ASCI I null (0). 

=001 Parameter is an integer. 

=010 Parameter is double by reference. 

=011 Ignore the parameter . 

Bits (10:3) - Param4 type (types same as for param5). 

Bits (7:3) - ParamS type (types same as for param5). 

Bits (4:3) - Param2 type (types same as for paramS). 

Bits (1:3) - Paraml type (types same as for paramS). 

Bit (0:1) 

= 1 Ignore rest of word and parameters paraml through paramS. 

=0 Rest of word, in 3 -bit groupings, will specify parameter types for 
paraml , param2, param3, param4, and paramS. 

Default: Parameters paraml through param5 will be ignored. 

logical by value (optional) 

Parameter to be inserted into message. If parmask specifies type (string), 
paraml must pass the byte address (that is, @stringarray) of the byte array 
containing the string. If parmask specifies type 2 (double by reference), 
paraml must pass the word address (that is, @doublename) of the double - 
word identifier containing the value . 

logical by value (optional) 

Parameter to be inserted into message. Description is the same as for 

paraml . 

logical by value (optional) 

Parameter to be inserted into message. Description is the same as for 

par am 1 . 
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param4 



paramS 



msgdest 



errnum 



logical by value (optional) 

Parameter to be inserted into message. Description is the same as for 

par ami . 

logical by value (optional) 

Parameter to be inserted into message. Description is the same as for 

par ami. 

integer by value (optional) 

Integer value specifying the destination of the assembled message. Enter 
the file number of the destination file if the file is not SSTDLIST; for 
$STDLIST, enter 0. 

Default: $STDLIST if buff is not specified, no file if buff is specified. 

integer (optional) 

Integer identifier to which an error number is returned. Values returned 

are as follows : 

Successful execution. 

1 FREADL ABEL failed on catalog file . 

2 FREAD failed on catalog file . 

3 Specified setnum not found in catalog. 

4 Specified msgnum not found in catalog. 

6 Assembled message overflowed buffer (if msgdest was specified, 
however, message routed correctly). 

7 Write failed to destination file. 

8 Catalog file opened with improper access options . 

1 1 A filenum parameter not specified . 

1 2 A setnum parameter not specified . 

1 3 A msgnum parameter not specified . 

14 The setnum is <= 0. 

1 5 The setnum is > 62. 

1 6 The msgnum is <= . 

17 The buf f size is <= 0. 

1 8 The msgdest is < 0. 
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CONDITION CODES 

CCE Successful execution. 

CCL Intrinsic did not execute because of file system error. 

CCG Intrinsic did not execute. May have missing required parameter, invalid 

parameter, or invalid file number of catalog or destination file. CCG is 
also returned if setnum or msgnum is not found . 

ADDITIONAL DISCUSSION 

"Using GENMESSAGE to Insert Parameters in Messages" in Section V. 
Point-to-Point Workstation I/O Reference Manual (30000-90250). 
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GETDSEG 

INTRINSIC NUMBER 130 



Creates an extra data segment. 

SYNTAX 



L I LV 

GETDSEG (index, length >id) ; 



The GETDSEG intrinsic creates or acquires an extra data segment. The number of extra data segments 
that can be requested, and the maximum size allowed these segments, are limited by parameters 
specified when the system is configured. When an extra data segment is created, the GETDSEG in- 
trinsic returns a logical index number to the calling process. This index number is assigned by MPE 
and allows this process to reference the segment in later intrinsic calls. 

The GETDSEG intrinsic is also used to assign the segment the identity that either allows other processes 
in the job or session to share the segment, or that declares it private to the calling process. If the 
segment is sharable , other processes can obtain its logical index (through GETDSEG) and use this index 
to reference the segment. Thus, the logical index is a local name that identifies the segment 
throughout any process that obtained the index with the GETDSEG call. The logical index need not be 
the same value in all processes sharing the data segment. The identity, on the other hand, is a job- 
wide or session-wide name that permits any process to determine the logical index of the segment. If 
the intrinsic is called in User Mode, then the data segment is initially filled with zeros. 

When GETDSEG is called in User Mode, all subsequent calls to intrinsics that use index must now be in 
User Mode. When GETDSEG is called in Privileged Mode, all subsequent calls to intrinsics that use in- 
dex must now be in Privileged Mode (version G. 01 .00 or later). 



PARAMETERS 

index 



length 



id 



logical (required) 

A word to which the logical index of the data segment , assigned by MPE , is 
returned. When GETDSEG is called in User Mode, index is a logical index of 
the assigned data segment; if an error is found, index will be set to 
%2000-%2004. When GETDSEG is called in Privileged Mode, index is the 
actual Data Segment Table (DST) entry number for the data segment that 
was assigned . 

integer (required) 

The maximum size of the data segment requested , if the segment is not yet 
created. If the segment already exists, the word to which the maximum 
size of the segment is returned. 

logical by value (required) 

A word containing the identity that declares the data segment sharable be- 
tween other processes in the job/session, or private to the calling process. 
For a sharable segment, id is specified as a nonzero value. If a data seg- 
ment with the same identification already exists, it is made available to the 
calling process. Otherwise, a new data segment, sharable within the 
job/session, is created with id. For a private data segment, an id of zero 
must be specified. 
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CONDITION CODES 

CCE Request granted. A new segment was created . 

CCG Request granted. An extra data segment with this identity exists already. 

CCL Request denied. An illegal length was specified (index is set to %2000). 

The process requested more than the maximum allowable number of data 
segments {index is set to %2001). Sufficient storage was not available for 
the data segment (index is set to %2002). A stack expansion necessary to 
satisfy the request could not be done because the stack was frozen (index set 
to %2003). A stack expansion is usually not necessary to get an extra data 
segment. There is not enough room in the job definition table to make an 
entry for the extra data segment (index set to %2004). 

SPECIAL CONSIDERATIONS 

Data Segment Management (DS) capability required. 

If the index parameter will be used with the SWITCHDB intrinsic, GETDSEG must be called in 
Privileged Mode (PM). 

ADDITIONAL DISCUSSION 

"Creating an Extra Data Segment" in Section III. 
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GETINFO 

INTRINSIC NUMBER 87 



Retrieves the info string and parm value from the :RUN command or CREATEPROCESS intrinsic. 
(Available G.02.00 version or later.) 

SYNTAX 



0-V BA I I 

GET I NFD (.info , info ' I ength , parm ) ; 



The GET I NFD intrinsic provides user programs with the ability to retrieve the info string and the parm 
value entered in the :RUN command, or given in the CREATEPROCESS intrinsic. The info string is 
returned in the byte array info and the parm value is returned in parm. If the info string is longer 
than the length specified by info'length only the amount of the string up to the info'length is returned. 

FUNCTIONAL RETURN 

result Integer. The possible values returned are: 

: The intrinsic executed successfully . 

1 : Error. This occurs when the info array is passed in, but the length is 
invalid or omitted. 



PARAMETERS 

info 
info'length 



parm 



byte array (optional) 

Specifies where the info string is to be returned. If not provided, the info 

string will not be returned. 

integer (optional) 

This parameter both passes and receives a length. When calling, this should 
contain a positive integer specifying the length, in bytes, of info. This is 
only required if info is specified . 

When returning from the call, the real length of the info string will be in 
info'length. When returning from the call, info'length will contain the 
smaller of either the real length of the info string or the original info'length 
value. 

integer (optional) 

Specifies where the parm value will be returned. 



CONDITION CODES 

The condition code remain unchanged . 
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ADDITIONAL DISCUSSION 

The CREATEPROCESS discussion in this section. 
MPE V Commands Manual (32033-90006). 
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GETJCW 

INTRINSIC NUMBER 73 



Returns the value of the system -defined Job Control Word JCW. 

SYNTAX 



L 
«TCW:=GETJCW; 



The GETJCW intrinsic returns the value of the system -defined Job Control Word to the calling process. 

FUNCTIONAL RETURN 

JCW logical (optional) 

A logical variable containing the Job Control Word. This word is struc- 
tured for a desired purpose by the calling program through the SET JCW in- 
trinsic or PUT JCW intrinsic. 



CONDITION CODES 

The condition code remains unchanged. 

ADDITIONAL DISCUSSION 

"User-Defined Job Control Words" in Section V. 
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GETLOCRIN 

INTRINSIC NUMBER 30 
Acquires local RINs. 

SYNTAX 



LV 
GETLDCR I Htorincount ) ; 



Just as global Resource Identification Numbers (RINs) must be acquired by users before they can be 
used in jobs/sessions, local RINs must be acquired by a job/session before they can be used within the 
job/session. This is done by using the GETLOCR I N intrinsic . 

PARAMETERS 

Tpvnctnmb logical by value (required) 

The number of local RINs to be acquired by the job/session. The maximum 
• number of RINs available is defined when the system is configured. 

CONDITION CODES 

CCE Request granted. 

CC G Request denied. RINs already are allocated to this job. Additional RINs 

cannot be allocated until these RINs are released. 

CCL Request denied. Not enough RINs are available to satisfy this call. None 

are allocated to this job. 

ADDITIONAL DISCUSSION 

"Resource Management" in Section III. 
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GETORIGIN 

INTRINSIC NUMBER 105 



Determines the source of an activation call for a process . 

SYNTAX 



i 

source : =GET0R I G I N ; 



After a suspended process is reactivated , it can determine whether the source of the activation request 
was its father process , one of its son processes , or whether the reactivation was by an interrupt or the 
timer. 

FUNCTIONAL RETURN 

source integer (optional) 

This intrinsic returns one of the following codes : 

Was not activated by the father nor the son . 

1 Activated by the father. 

2 Activated by a son. 

CONDITION CODES 

The condition code remains unchanged. 

SPECIAL CONSIDERATIONS 

Process Handling (PH) capability required. 

ADDITIONAL DISCUSSION 

"Determining Source of Activation" in Section III. 
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GETPRIORITY 

INTRINSIC NUMBER 120 
Changes the priority of a process. 

SYNTAX 



0-V IV LV IV 

GETPR I OR I TY (pin, priorityclass >rarik ) ; 



When a process is created , it is scheduled on the basis of a priority class assigned by its father. After 
this point, the priority class of the created process can be changed at any time by using the 
GETPRIORITY intrinsic. 



NOTE 



A process can change its own priority or that of its son , 
but it cannot reschedule its father. 



The GETPRIORITY intrinsic will abort the calling process if the requested priorityclass exceeds the 
maximum allowable priorityclass of the rescheduled process, or specif ies an invalid priorityclass. 



PARAMETERS 

pin 

priorityclass 



integer by value (required) 

An integer specifying the process whose priority is to be changed. If this is 
a son process , the integer is the Process Identification Number (PIN) of the 
process. If this is the calling process, the integer is zero. 

logical by value (required) 

A 16 -bit word that contains two ASCII characters describing the priority 
class in which the process is rescheduled. This may be AS, BS, CS, DS, or 
ES. For users running in Privileged Mode , the priorityclass parameter may 
be specified as an absolute number by acA, where x is an 8 -bit priority 
number and A is the ASCII character "A". For example, a request for a 
priorityclass of 31 in the master queue would be requested as %017501. 
Note that an absolute priority must be specified in order to overcome the 
MAXPR I setting of an account . 



NOTE 



Scheduling a process into the AS or BS priority class (assuming 
the maximum priority for the process allows such a specifica- 
tion) can result in the rescheduled process deadlocking the sys- 
tem or locking out system and user processes from execution . 
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rank integer by value (optional) 

This parameter is used only for the "AS" priority class. It will be added to 
the "AS" priority value if supplied and is ignored in all other cases. 

CONDITION CODES 

CCE Request granted. 

CCG Request denied because the process specified does not exist. 

CCL Request denied because an illegal PIN was specified. 

SPECIAL CONSIDERATIONS 

Split -stack calls permitted. 

Process Handling (PH) capability required. 

Must be running in Privileged Mode to specify absolute priority . 

ADDITIONAL DISCUSSION 

"Rescheduling Processes" in Section HI. 
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GETPRIVMODE 

INTRINSIC NUMBER 200 
Dynamically enters Privileged Mode. 

SYNTAX 



o-p 
GETPRIVMODE; 



The GETPRIVMODE intrinsic switches a temporarily privileged program from the non -Privileged Mode 
to the Privileged Mode. This intrinsic sets the Privileged Mode bit in the status register bit (9: 1)=1 , 
but leaves the Privileged Mode bit in the Code Segment Table (CST) entry for the executing segment 
unchanged. The status register, rather than the CST, determines a mode change when running in 
Privileged Mode. Thus, if additional segments are to be run as part of the program, they will be run 
in Privileged Mode unless GETUSERMODE is called specifically to return to the non-Privileged Mode. 
The calling process is aborted if the program file does not possess the Privileged Mode (PM) capability, 
and the CST indicates non -Privileged Mode. 

CONDITION CODES 

CCE Request granted. The program was in non -Privileged Mode when the in- 

trinsic call was issued. 

CCG Request granted. The program was already in Privileged Mode when the 

intrinsic call was issued. 

CCL Not returned by this intrinsic. 

SPECIAL CONSIDERATIONS 

Privileged Mode (PM) capability required. 



CAUTION 



The normal checks and limitations that apply to the 
standard users in MPE are bypassed in Privileged Mode. 
It is possible for a Privileged Mode program to destroy 
file integrity, including the MPE operating system soft- 
ware itself. Hewlett-Packard will investigate and at- 
tempt to resolve problems resulting from the use of 
Privileged Mode code. This service, which is not 
provided under the standard Service Contract, is avail- 
able on a time and materials billing basis. 
Hewlett-Packard will not support, correct, or attend to 
any modification of the MPE operating system software. 



ADDITIONAL DISCUSSION 

"Entering Privileged Mode" in Section HI. 
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GETPROCID 

INTRINSIC NUMBER 112 



Requests PIN of a son process. 

SYNTAX 



I IV 

pin : =GETPROCIDCnumson) ; 



A process can determine the Process Identification Number (PIN) assigned to any of its sons by using 
the GETPRDC I D intrinsic . 

FUNCTIONAL RETURN 

pin integer (optional) 

The PIN of the specified son process. 

PARAMETERS 

numson integer by value (required) 

A number from 1 to n which specifies the chronological son's PIN. The 
value n cannot exceed the number of sons in existence. For example, a 
father process has three sons and wants to know the PIN of the second son. 
The value of numson then would be 2. 

If n exceeds the number of sons currently attached to this calling process , a 
zero is assumed. If n is less than 1 , the PIN of the first son (or zero if no 
sons exist) is returned. 

CONDITION CODES 

The condition code remains unchanged. 

SPECIAL CONSIDERATIONS 

Process Handling (PH) capability required. 

ADDITIONAL DISCUSSION 

"Determining Son Process" in Section III. 
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GETPROCINFO 

INTRINSIC NUMBER 110 
Requests status information about a father or son process. 

SYNTAX 



D IV 

statin fo : =GETPRDC I NFD (pin) ; 



Information about a father or son process can be obtained with the GETPROCINFO intrinsic. 

FUNCTIONAL RETURN 

statinfo double (optional) 

A double-word message denoting information about a father or son process. 
The words contain information in the following manner: 

Word 1 : 

Bits (8:8) - The priority number of the process in the master queue. 

Bits (0:8) - Reserved for MPE. 

These bits are set to zero by the system. 

Word 2: 

Bit (15:1) -Activity state . 

This bit has the following settings : 

=0 The process is suspended . 

=1 The process is active . 

Bits (13:2) - Suspension condition. 

The following settings apply only if bit (1 5: 1)=0: 

=00 Is not used. 

=01 The source of the expected activation is the father. 

= 1 The source of the expected activation is the son . 

= 1 1 The source of the expected activation is either the father or the son . 

Bits (9:4) - Reserved for MPE. 

These bits are set to zero by the system. 
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Bits (7:2) - Origin of the last ACTIVATE intrinsic call denoted by the fol- 
lowing bit settings : 

=00 The process was activated by MPE. 

=01 The process was activated by the father. 

= 1 The process was activated by the son . 

= 11 Is not used. 

Bits (4:3) - Queue Characteristics. 

The characteristics are defined by the following bit settings : 

=00 1 DS or ES priority class. 

=010 CS priority class . 

= 100 Linearly scheduled (AS, BS, or Master queue). 

Bits (0:4) - Reserved for MPE. 

These bits are set to zero by the system. 

PARAMETERS 

pin integer by value (required) 

The process to which the returned message pertains. If this is a request for 
a father process, pin must be zero. If it is a request for a son process, pin is 
the PIN of that process. 

CONDITION CODES 

CCE Request granted. 

CCG Request denied because the process is being terminated. 

CCL Request denied because an illegal PIN was specified. 

SPECIAL CONSIDERATIONS 

Split-stack calls permitted. 

Process Handling (PH) capability required. 

ADDITIONAL DISCUSSION 

"Determining Process Priority and State" in Section III. 
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GETUSERMODE 

INTRINSIC NUMBER 201 
Dynamically returns a program to non -Privileged Mode. 

SYNTAX 



GETUSERMODE; 



The GETUSERMODE intrinsic changes a temporarily privileged program from Privileged to non- 
Privileged Mode. 

This intrinsic changes the Privileged Mode bit in the status register, bit (9: 1 )=0, and is the comple- 
ment of the GETPRIVMODE intrinsic. 

CONDITION CODES 

CCE Request granted. The process was in Privileged Mode when the intrinsic 

call was issued. 

CCG Request granted. The program was in non -Privileged Mode when the in- 

trinsic call was issued. 

CCL Not returned by this intrinsic. 

SPECIAL CONSIDERATIONS 

Privileged Mode (PM) capability required. 

ADDITIONAL DISCUSSION 

"Entering Non -Privileged Mode" in Section III. 
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INITUSLF 

INTRINSIC NUMBER 82 



Initializes a USL file to the empty state. 

SYNTAX 



I IV I 

errnum : = I N I TUSLFCms lfnum>recO ) ; 



The INITUSLF intrinsic initializes the first record (record 0) of a USL file to the empty state. 

FUNCTIONAL RETURN 

errnum integer (optional) 

If no error occurs, no value is returned. If an error occurs, one of the fol- 
lowing is returned : 

An unexpected end-of-file was encountered when writing to uslfnum. 

1 Unexpected input/output error occurred . 

PARAMETERS 

uslfnum integer by value (required) 

A word supplying the file number of the USL file. 

recO integer array (required) 

A 128-word buffer, corresponding to the first record of the USL file 
(record 0) , to be initialized to the empty state. This buffer should be set to 
all zeros. The intrinsic will set certain values in record before returning 
to the calling program. 

CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic . 

CCL Request denied; an error number is returned to errnum. 

ADDITIONAL DISCUSSION 

MPE Segmenter Reference Manual (30000-9001 1). 
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IODONTWAIT 

NO INTRINSIC NUMBER ASSIGNED 
Initiates completion operations for an I/O request . 

SYNTAX 



I 0-V IV LA I L 

fnum : = I ODONTUIA IT (filenum, target , tcotmt ,cstation ) ; 



The IODONTWAIT intrinsic operates the same as IOWA IT with one exception: if IOWA IT is called and 
no I/O has completed , then the calling process is suspended until some I/O completes ; if I ODONTWA I T 
is called and no I/O has completed , then control is returned to the calling process (CCE is returned 
and the result of I ODONTWA IT is zero). 



FUNCTIONAL RETURN 



fnum 



integer (optional) 

An integer representing the file number for which the completion occur- 
red. If no completion occurred, zero is returned. 



PARAMETERS 

filenum 
target 



tooimt 



c station 



integer by value (required) 

A word supplying the file number for which there is a pending I/O request . 
If zero is specified, the IODONTWAIT intrinsic will check for any I/O 
completion . 

logical array (optional) 

A word pointer specifying the DB-relative address of the user's input 
buffer. This buffer must be large enough to contain the input record. It 
should be the same buffer specified in the original I/O request if that 
request was a read. 

integer (optional) 

A word to which a positive integer representing the length of the received 
or transmitted record is returned. If the original request specified a byte 
count, the integer represents bytes; if the request specified words, the in- 
teger represents words. Note that this parameter is pertinent only if the 
original request was a read. The FRE AD intrinsic always returns zero as its 
functional return if NOW AIT I/O is specified. In this case, the actual 
record length is returned in the tcount parameter of IODONTWAIT. 

Default: The length of the record is not returned. 

logical (optional) 

Used for distributed systems to return the number of the calling station 

when completed . 
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CONDITION CODES 

CCE Request granted. If the functional return is not zero then I/O completion 

occurred with no errors. A returned to fnum indicates that no I/O has 
completed. 

CCG An end-of-file condition was encountered. 

CCL Request denied. Normal I/O completion did not occur because there were 

no I/O requests pending, a parameter error occurred, or an abnormal I/O 
completion occurred. 

SPECIAL CONSIDERATIONS 

You must be running in Privileged Mode to specify FDPEN aoption NOW AIT I/O. 

ADDITIONAL DISCUSSION 

"Using the IOWAIT Intrinsic" in Section IV. 

Point-to-Point Workstation I/O Reference Manual (30000-90250). 
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IOWAIT 

INTRINSIC NUMBER 22 
Initiates completion operations for an I/O request. 

SYNTAX 



I 0-V IV LA I L 

fnum : = IOWA IT (.filenum, target } tcount ,cstaticn ) ; 



If a file has been opened with the NOW AIT I/O mode aoption of the FOPEN intrinsic (aoption bit 
(4:1) = 1), all read and write requests must be followed by the IOWA I Tor I ODONTWA IT intrinsic call. 
This intrinsic initiates completion operations for the associated I/O request, including data transfer 
into the user's buffer area if necessary. 

The IOWAIT intrinsic call must precede any subsequent I/O request against the file. Within this 
restriction, the IOWAIT intrinsic call can be delayed as long as desired to allow effective I/O and 
processing overlap . 



FUNCTIONAL RETURN 



fnum 



integer (optional) 

An integer representing the file number for which the completion occur- 
red. If no completion occurred, zero is returned. 



PARAMETERS 

filenum 

target 



tcoimt 



integer by value (optional) 

A word specifying the file number for which there is a pending I/O 
request. If zero is specified, the IOWAIT intrinsic will wait for the first 
I/O completion . 

logical array (optional) 

A word pointer specifying the DB -relative address of the user's input buff- 
er. This buffer must be large enough to contain the input record. It 
should be the same buffer specified in the original I/O request if that 
request was a read. This allows for proper recognition of :EOD where 
applicable. 

integer (optional) 

A word to which a positive integer representing the length of the received 
or transmitted record is returned. If the original request specified a byte 
count, the integer represents bytes; if the request specified words, the in- 
teger represents words. Note that this parameter is pertinent only if the 
original request was a read. The FREAD intrinsic always returns zero as its 
functional return if NOW AIT I/O is specified. In this case, the actual 
record length is returned in the tcount parameter of IOWAIT. 

Default: The length of the record is not returned. 
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cstatian logical (optional) 

Used for distributed systems to return the number of the calling station 
when completed. 

CONDITION CODES 

CCE Request granted. I/O completion occurred with no errors. 

CCG An end-of-file condition was encountered. 

CCL Request denied. Normal I/O completion did not occur because there were 

no I/O requests pending, a parameter error occurred, or an abnormal I/O 
completion occurred. 

SPECIAL CONSIDERATIONS 

You must be running in Privileged Mode to specify FDPEN aoption NO WAIT I/O. 
Split -stack calls permitted. 

ADDITIONAL DISCUSSION 

"Using the IOWAIT Intrinsic" in Section IV. 

Point-to-Point Workstation I/O Reference Manual (30000-90250). 
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JOBINFO 

INTRINSIC NUMBER 180 

Provides access to job/session related information. (Available on version G. 01 .00 or later). 

SYNTAX 



0-V IV D LA IV LA I 
JUBlHFDCjsindyJSihtnn, status 1 7 itemnuml ,iteml serrornuml ] 

[ , itemnvmZ , item2 , en>ozmum2 ] 
[ , itermumZ , itemZ , errornumZ 1 
[ , itemnum4 , item4 3 errornum4 1 
[ , -itemnumS , itemS , errornumS 1 ) ; 



JOBINFO provides access to information related to any job/session that is current to the system. This 
intrinsic is expandable , and is written so the addition of further functions will be straightforward . 



PARAMETERS 

jsind 



JSihvm 



status 



integer by value (required) 

An integer indicating whether the JS#nnn denotes a session or job : 

1 JSftnnn is a session . 

2 JSftnnn is a job. 

double (required) 

A double-value, 32 bits, identifying a job or session for which information 

will be retrieved. 

logical array (required) 

A two-word logical array to report the overall success/failure of the call. 
Only the first word contains significant information. The success/failure 
of the call is indicated by the following returns : 

Successful call . All errornums equal zero. 

1 Semi -successful call. One or more errornum(s) were returned with 
nonzero values. 

2 Unsuccessful call . All errornums were returned with nonzero values . 

3 Unsuccessful call. Syntax error in calling sequence. 

4 Unsuccessful call . Unable to retrieve JSttnnn . 

5 Process terminated. The process terminated during the start of 
retrieval . 
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itemnum 



item 



errornvm 



integer by value (optional) 

Cardinal number of the item desired. This specifies which item value is to 

be returned (Refer to "Item#" in Table 2-6). 

logical array (optional) 

Name of a reference parameter (whose data type corresponds to the data 
type for the desired information) to which the desired information is 
returned (Refer to "Item Value" in Table 2-6). 

All possible itemnum and item parameters are output parameters with one 
exception. Item Number 1 can be used for an input or output parameter. 
Item Number 1 is an input parameter only if the user is identifying a job or 
session by passing a character string containing the logon ID, 
Ijsname ,1username .acctname . Otherwise, it is an output parameter. The 
maximum number of characters returned is twenty -six. The returned 
string will be left -justified and padded with blanks. 

integer (optional) 

A returned integer specifying the success or failure of the retrieval of each 

item. The returned values are : 



Successful information retrieval. 

1 Invalid itemnum (item number). 

2 Desired information not pertinent to the given JSftnnn (e.g. user 
specifies a session number and wishes to know if a job had RESTART 
option). 

3 User has insufficient capability to access this information. 

4 The desired information is no longer available (e.g. returned when 
spoolf iles are processed) . 

SPECIAL CONSIDERATIONS 

A user without System Manager (SM) or Account Manager (AM) capability can only retrieve infor- 
mation about the jobs/sessions logged onto under the user name and account. A user with AM 
capability , but not SM capability will be restricted to access information concerning account sessions 
and jobs; a user with SM capability will be able to retrieve information concerning all sessions and 
jobs. The exception to the above security will be access to items, through MPE commands, which are 
normally available to the user who does not have any special capabilities. 

CONDITION CODES 

The condition code remains unchanged. 

ADDITIONAL DISCUSSION 

"Identifying a Job or Session with JOBINFO" in Section V. 
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Table 2-6. Item Values Returned By JOBINFO 



ITEM* 


ITEM VALUE (Information Returned) 


DATA TYPE 


1 


[j sname ,] user account (See Note 1) 


LA 


2 


Session/job name (See Note 2) 


LA 


3 


User name (See Note 2) 


LA 


4 


User logon group (See Note 2) 


LA 


5 


User account (See Note 2) 


LA 


6 


User home group (See Note 2) 


LA 


7 


Session/job introduction time (See Note 3) 


LA 


8 


Session/job introduction date (See Note 4) 


LA 


9 


Input ldev/class name (See Note 2) 


LA 


10 


Output ldev/class name (See Note 2) 


LA 


11 


Current job step (See Note 5) 


LA 


12 


Current number of active jobs 




13 


Current number of active sessions 




14 


Job input priority 




15 


Job/session number 


D 


16 


JOBFENCE 




17 


Job output priority 




18 


Number of copies 




19 


Job limit (system) 




20 


Session limit (system) 




21 


Job deferred (See Note 6) 




22 


Main PIN - CI PIN for job/session 




23 


Original job-spooled (See Note 6) 




24 


RESTART option (See Note 6) 




25 


Sequenced - job (See Note 6) 




26 


Term code (See Note 7) 




27 


CPU limit 




' 28 


Session/job state (See Note 8) 




29 


User's local attributes 




30 


SSTDIN spoolfile number (See Notes 9 & 10) 




31 


$STDIN spoolfile status (See Notes 9 & 11) 




32 


SSTDLIST spoolfile number (See Notes 9 & 10) 




33 


SSTDLIST spoolfile status (See Notes 9 & 11) 




34 


Length of current job step of Item Number 11 




35 


:SET STDLIST=DELETE invoked (See Note 12) 




36 


Job Information Table data segment number 
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Table 2-6. Item Values Returned By JOBINFO (Continued) 



1. 


Can be used as an inp 


ut or output parameter. If used as an input parame- 




ter, a maximum of 26 


ASCII characters, plus one for a binary terminator 




is allowed. The 


input string must be in the form of 




[ j sname , juser. account 


The wildcard character @ is not allowed. If used 




as an output parameter, the logical array must be 13 words long. Output 




is left-justified and 


padded wit h blanks . 


2. 


An ASCII output parameter. Logical arrays must be four words long. 




Output is left-justif 


Led and padded with blanks. 


3. 


Returns a 32-bit double-word in a form to be used by the FMTCLOCK intrin- 




sic. If for a schedu 


led job, it will be the time when the job enters the 




WAIT state. 




4. 


Returns a 16-bit logical word in a form to be used by the FMTCALENDAR in- 




trinsic. If for a scheduled job, it will be the date when the job ent- 




ers the WAIT state . 




5. 


Returns a maximum of 


283 ASCII characters, and is the image of the com- 




mand currently execut 


ing. The logical array must be long enough to ac- 




commodate the expected command image. 


6. 


Returns the values: 


- No 




1 


- Yes 


7. 


Returns the values: 


- Regular terminal 




1 


- Regular terminal with special logon 




2 


- APL terminal 




3 


- APL terminal 


8. 


Returns the values: 2 


- Executing 




4 


- Suspending 




32 


- Wait 




48 


- Initialization 




56 


- Scheduled 


9. 


Returns data for current jobs and sessions. $STDIN/$STDLIST files only. 


10. 


Returns the spoolfile 


number as an integer. 


11. 


Returns the values: 


- Active 




1 


- Ready 




2 


- Open 




3 


- Reserved 


12. 


Returns the values: 


- SSTDLIST will be saved 




1 


- :SET STDLIST=DELETE is invoked 
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KILL 

INTRINSIC NUMBER 102 
Deletes a son process. 

SYNTAX 



IV 
KILL(pin); 



A process can delete one of its sons by using the KILL intrinsic. 

PARAMETERS 

pin integer by value (required) 

A word containing the Process Identification Number (PIN) of the process 
to be deleted . 

CONDITION CODES 

CCE Request granted. 

CCG Request granted. The specified process was terminating. 

CCL Request denied because an illegal PIN was specified. 

SPECIAL CONSIDERATIONS 

Process Handling (PH) capability required. 

ADDITIONAL DISCUSSION 

"Deleting Processes" in Section III. 
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LOADPROC 

INTRINSIC NUMBER 80 



Dynamically loads a library procedure . 

SYNTAX 



I BA IV I 

iden tnum: =L0ADPR0C (procname ,lib i plabel~) ; 



LDADPROC dynamically loads a library procedure, and any external procedures it has referenced. 



FUNCTIONAL RETURN 



identnum 



integer (optional) 

An identity number required for use in unloading the procedure. If a 

loader error occurs, the identity number represents a loader error code. 



PARAMETERS 

procncane 
lib 



plabel 



byte array (required) 

Contains the name of the procedure to be loaded. The name must be ter- 
minated by a blank . 

integer by value (required) 

An integer value of 0, 1 , or 2, to request library searching for the proce- 
dure residing in the logon group of the user, as follows: 

Search the system library only. 

1 Search the account library, then the system library. 

2 Search the group library first, the account library second, and the sys- 
tem library last. 

integer (required) 

The word to which the procedure's label {plabel) is returned. This is the 

external plabel so that the SPL construct ASSEMBLE CPCAL 0) may be used. 



CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied. The value returned to identnum is a loader error code. 



ADDITIONAL DISCUSSION 

"Dynamic Loading and Unloading of Library Procedures" in Section V. 
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LOCKGLORIN 

INTRINSIC NUMBER 34 
Locks a global RIN. 

SYNTAX 



IV L BA 

LOCKGLDR I N (x*irmum 3 lockcond ,rinpassword ) ; 



Any global Resource Identification Number (RIN) assigned to a group of users can be locked , one job 
at a time, by using the LDCKGLORIN intrinsic. When this is done, any other jobs that attempt to lock 
this RIN are suspended . 

To use the LOCKGLORIN intrinsic, you must know both the RIN number and the RIN password. 
Multiple RIN (MR) capability is required to lock two or more global RINs simultaneously. An at- 
tempt by a user with standard capabilities to lock two or more RINs simultaneously aborts the process. 



PARAMETERS 



x*twuaa 



lockcond 



xnnpasstiord 



integer by value (required) 

A word specifying the RIN number of the resource to be locked. This is 
the RIN number furnished in the :GETR IN command. Refer to the MPE V 
Commands Reference Manual (32033-90006) for a description of the 
: GETR I N command . 

logical (required) 

A word specifying conditional or unconditional RIN locking, through bit 

(15:1). Bit ( 1 5 : 1 ) has the following settings : 

=0 Locking takes place only if the RIN is immediately available. If the 
RIN is not immediately available, control returns to the calling process 
immediately with the condition code CCG . 

= 1 Locking will take place unconditionally. If the RIN is not available, 
the calling process suspends until it becomes available. 

All other bits are ignored. 

byte array (required) 

Contains the RIN password assigned through the : GETR IN command. This 
array must be a minimum of 1 bytes in length and must be terminated by 
a nonalphanumeric ASCII character (a blank is recommended). 
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CONDITION CODES 

The condition codes possible if lockcond bit ( 1 5 : 1 )= 1 are : 

CCE Request granted. If the calling process had already locked the RIN, 

lockword bit ( 1 5 : 1 )= 1 . If the RIN was free , lockword bit ( 1 5 : 1 )=0 . 

CCG Not returned. 

CCL Request denied because of invalid RIN. Rinnum is not a global RIN or the 

value is out of bounds for the RIN table. 

The condition codes possible if lockcond bit (15 : 1)=0 are: 

CCE Request granted. If the calling process had already locked the RIN, 

lockword bit ( 1 5 : 1 )=0 . If the RIN was free , lockword bit ( 1 5 : 1 )= 1 . 

CCG Request denied because the RIN was locked by another job. 

CCL Request denied because of invalid RIN. Rinnum is not a global RIN or the 

value is out of bounds for the RIN table . 

SPECIAL CONSIDERATIONS 

Multiple RIN (MR) capability is required if you are doing the following: 

• Locking more than one global RIN at a time within a process. 

• Locking one RIN within a process tree. 

• Locking any files (for example, database). 

• Using local RINs with global RINs. 

ADDITIONAL DISCUSSION 

"Resource Management" in Section III. 



2-197 



LOCKLOCRIN 

INTRINSIC NUMBER 32 
Locks a local RIN. 

SYNTAX 



IV L 

LQCKLOCRWirinnum, lockcond) ; 



Any local Resource Identification Number (RIN) assigned to a job can be locked, one process at a 
time, by using the LOCKLOCRIN intrinsic. When this is done, other processes within the job that at- 
tempt to lock that RIN are suspended until the locked RIN is released. 

PARAMETERS 

rirtman integer by value (required) 

A number specifying one of the previously allocated local RINs, designated 
by an integer from 1 to the value specified in the rincount parameter of the 
GETLOCR IN intrinsic. 

lockcond logical (required) 

A word specifying conditional or unconditional locking, through bit 
(15:1). The settings for bit (15:1) are as follows : 

=0 Locking takes place only if the RIN is immediately available. If it is 
not, control returns to the calling process immediately with CCG. 

= 1 Locking takes place unconditionally. If the RIN is not available, the 
calling process suspends until the RIN becomes available . 

All other bits are ignored. 

CONDITION CODES 

The condition codes possible if lockcond bit ( 1 5 : 1 )= 1 are : 

CCE Request granted. If the calling process had already locked the RIN, 

lockcond bit ( 1 5 : 1 )■ 1 . If the RIN was free , lockcond bit ( 1 5 : 1 )=0. 

CCG Not returned. 

CCL Request denied because the RIN was invalid; the rinnum was too large, no 

local RIN was allocated , or rinnum specified a number less than or equal to 
zero. 
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The condition codes possible if lockcond bit (15:1 )=0 are : 

CCE Request granted. If the calling process had already locked the RIN, 

lockcond bit ( 1 5 : 1 )= 1 . If the RIN was free , lockcond bit ( 1 5 : 1 )=0 . 

CCG Request denied because the RIN was locked by another process. 

CCL Request denied because the RIN was invalid ; the rinnum was too large , no 

local RIN was allocated , or rinnum specified a number less than or equal to 
zero. 

ADDITIONAL DISCUSSION 

"Resource Management" in Section III. 
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LOCRINOWNER 

INTRINSIC NUMBER 36 
Determines PIN of process that has locked a local RIN. 

SYNTAX 



I IV 

pin : =LDCRINDWNERCi»in7iMm) ; 



After local RINs have been acquired by a process , they can be locked and unlocked by other processes 
in the process structure. LOCRINOWNER determines the PIN (Process Identification Number) of the 
process that has a particular RIN locked. 

FUNCTIONAL RETURN 

pin integer (optional) 

If the particular RIN is locked by the father process of the process which 
called LOCRINOWNER, a is returned. The PIN of the son or brother 
process which has the local RIN locked is returned. 

PARAMETERS 

rinnum integer by value (required) 

The number of the local RIN (from 1 to the value specified in the rincount 
parameter of the GETLOCRIN intrinsic) for which the PIN of the locking 
process is to be determined. 

CONDITION CODES 

CCE Request granted. 

CCG Request denied . The local RIN specified by rinnum is not currently locked 

by any process. 

CCL Request denied. The rinnum parameter was invalid (i.e. rinnum was less 

than or equal to 0, greater than the RIN table size, or greater than the 
number of local RINs currently allocated to this process structure). 

ADDITIONAL DISCUSSION 

"Resource Management" in Section III. 
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LOGINFO 

INTRINSIC NUMBER 215 



Provides information about an opened user's logging file (whole file set). (Available on version 
G.02.00 or later.) 

SYNTAX 



0-V DV I IV BA 

LOGINFD (index t status [ 7 itemmanl ,iterm>all] 

[ ,itemnan2>itenaxzl21 
[ ,itenmon3,itenaxil3] 
[ ,itemnum4 t itemoal4 ] ) ; 



The LOGINFO intrinsic is used to obtain information about the whole logging file set. Up to four 
items of information can be retrieved by specifying one or more itemnum/itemval pairs. The itetn- 
num/itemval parameters must appear in pairs . 



PARAMETERS 

index 
status 



double by value (required) 

The index parameter returned from OPENLOG. Identifies the user access to 

the logging file. 

integer (required) 

One of the following integers indicating the success/failure of the intrinsic 

call: 

Message No. Meaning 





1 

2 
3 

4 
5 
6 

7 



No error occurred for this call. 

User requested NOW AIT mode and the logging process is 
busy. 

Parameter out of bounds in logging intrinsic. 

Request to open or write to a logging process that is not 
running. 

Incorrect index parameter passed to a logging intrinsic . 

Incorrect mode parameter passed to a logging intrinsic . 

User request denied because logging process is suspended . 

Illegal capability. Must have User Logging (LG) and System 
Supervisor (OP) capabilities to use a logging intrinsic. 
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irtenrtum 



itemoal 



Meaning 

Incorrect password passed to logging intrinsic. 

Error occurred while writing logging file. 

System is out of disc space; logging cannot proceed. 

No more logging entries. 

Invalid access to logging file. 

End -of -file on user logging file. 

Invalid logging identifier. 

Either itetnnum or itemval is missing . 

Invalid item number. 



integer by value (optional) 

Cardinal number of the item desired; this specifies which item value is to 

be returned. (Refer to Item# in Table 2-7.) 

byte array (optional) 

The value of the item specified by the corresponding item number ; the data 
type of the item value depends on the item itself. (Refer to Item Value in 
Table 2-7.) 



Message No . 


8 


9 


12 


13 


14 


15 


16 


17 


18 



CONDITION CODES 

The condition code remains unchanged. 

SPECIAL CONSIDERATIONS 

User Logging (LG) and System Supervisor (OP) capabilities required. 

ADDITIONAL DISCUSSION 

"User Logging" in Section III. 
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Table 2-7. Item Values Returned By LOGINFO 



ITEMt 


ITEM VALUE 


TYPE 


1 


Total # of records written in current file 


D 




2 


Current file size 


D 




3 


Current file space left 


D 




4 


Number of users 


I 




5 


Total records written in whole set 


D 




6 


Current logfile name 


36 


bytes 


7 


Current logfile type: disc, tape, sdisc , ctape 


I 




8 


Previous logfile name 


36 


bytes 


9 


Previous logfile type: disc, tape, sdisc, ctape 


I 




10 


CHANQELOQ allowed 


L 




11 


AUTO allowed 


L 




12 


Current file sequence number 


I 




13 


Log status 

= Inactive 

1 = Active 

2 = CHANGELOG pending 

3 = STOP pending 


I 
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LOGSTATUS 

INTRINSIC NUMBER 214 



Provides information about a current opened user logging file. 

SYNTAX 



D LA I 

LOGSTATUS (index, loginfo ^status) ; 



The LOGSTATUS intrinsic is used to obtain information about the current opened logging file. Its 
primary use is to determine the amount of space used and remaining in a disc logging file. 



PARAMETERS 

index 

loginfo 



status 



double (required) 

The parameter returned from OPENLOG that identifies your access to the 

logging system. 

logical array (required) 

A formatted array in which the following information is returned: 

Words and 1 - Total records written in current logging file. 

Words 2 and 3 - The size, in records, of the current logging file. 

Words 4 and 5 - The space , in records , remaining in the current logging 
file. 



Word 6 



- The number of users using the logging system. 



integer (required) 

One of the following integers indicating the success/failure of the intrinsic 

call: 

Message No . Meaning 




1 

2 
3 

4 
5 
6 



No error occurred for this call . 

User requested NOW AIT mode and the logging process is 
busy. 

Parameter out of bounds in logging intrinsic . 

Request to open or write to a logging process that is not 
running. 

Incorrect index parameter passed to a logging intrinsic . 

Incorrect mode parameter passed to a logging intrinsic . 

User request denied because logging process is suspended . 
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Message No . Meaning 

7 Illegal capability. Must have User Logging (LG) and System 
Supervisor (OP) capabilities to use a logging intrinsic. 

8 Incorrect password passed to logging intrinsic. 

9 Error occurred while writing logging file. 

1 2 System is out of disc space , logging cannot proceed . 

1 3 No more logging entries. 

1 4 Invalid access to logging file. 

1 5 End-of-file on user logging file. 

16 Invalid logging identifier. 



CONDITION CODES 

The condition code remains unchanged . 

SPECIAL CONSIDERATIONS 

User Logging (LG) and System Supervisor (OP) capabilities required. 

ADDITIONAL DISCUSSION 

"User Logging" in Section III. 
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MAIL 

INTRINSIC NUMBER 106 
Tests mailbox status . 

SYNTAX 



L IV I 

status : =MA I L Cpin , count ) ; 



A process can determine the status of the mailbox used by its father or son with the MAIL intrinsic. If 
the mailbox contains mail that is awaiting collection by this process, the length of this message (in 
words) is returned to the calling process in the count parameter. This enables the calling process to in- 
itialize its stack in preparation for receipt of the message . 



FUNCTIONAL RETURN 

status 



PARAMETERS 

pin 
count 



logical (optional) 

One of the following which indicates the status of the mailbox : 



Status 
Returned 



1 



Meaning 

The mailbox is empty. 

The mailbox contains previous outgoing mail from this 
calling process that has not yet been collected by the des- 
tination process. 

The mailbox contains incoming mail awaiting collection 
by this calling process. The length of the mail is return- 
ed in count . 

An error occurred because an invalid pin was specified 
or a bounds check failed . 

The mailbox is temporarily inaccessible because other in- 
trinsics are using it in the preparation or analysis of 
mail. 



integer by value (required) 

An integer specifying the mailbox tested. If this integer specifies the mail- 
box of a son process, it must be the Process Identification Number (PIN) of 
that son. Zero specifies the mailbox of a father process. 

integer (required) 

A word to which an integer denoting the length, in words, of any incoming 

mail in the mailbox is returned. 
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CONDITION CODES 

CCE Request granted. The mailbox status was tested . 

CCG Request denied because an illegal pin parameter was specified. The value 

of 3 is returned to the calling process through status . 

CCL Not returned by this intrinsic. 

SPECIAL CONSIDERATIONS 

Process Handling (PH) capability required. 

ADDITIONAL DISCUSSION 

"Interprocess Communication" in Section III. 
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MYCOMMAND 

INTRINSIC NUMBER 71 
Parses (delineates and defines parameters for) a user-defined command image. 

SYNTAX 



I 0-V BA BA IV 

entryno : =MYCOMMAND(comtflK0e,deZimt. ters ,maxparms , 

I DA BA BP 

numparms 3 params,dict , defn ) ; 



You can extract and format the parameters of a command, other than an MPE command, for execu- 
tion by using the MYCOMMAND intrinsic within your program. This intrinsic also allows you to request 
the searching of a byte array , serving as a command dictionary , for a specified command . 

The MYCOMMAND intrinsic aborts the calling process if the number of characters in comimage exceeds 
255 characters and no delimiter is present. 



FUNCTIONAL RETURN 



entryno 



integer (optional) 

An integer specifying the command entry number. 

was not specified , this number is 0. 



If the diet parameter 



PARAMETERS 

comimage 



delimiters 



byte array (required) 
Contains either : 

• A command name (expected if the diet parameter is specified), fol- 
lowed by parameters, followed by a carriage-return character (%15). 
The command name is delimited by the first nonalphanumeric charac- 
ter, and cannot be preceded by any leading blanks. The parameters are 
formatted and referenced in the params array. Also, comimage is con- 
verted to uppercase and the byte array specified by diet is searched for a 
name matching the command. 

• Only command parameters (expected if the diet parameter is not 
specified), followed by a carriage -return character (%15). These 
parameters are formatted. Leading and trailing blanks are ignored. 
Lowercase is upshifted. In the byte array named for the comimage pa- 
rameter, the first character of the parameter list may be a leading 
blank . 

byte array (optional) 

A byte array containing a string of up to 32 legal delimiters, each of which 
is an ASCII special character. The last character must be a carriage return. 
Each delimiter is identified later by its position in this string. 

Default: If this parameter is omitted, the delimiter array ", = ; (carriage 
return)" is used. 
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maxpartns 

rtumpctrms 
popcorns 



integer by value (required) 

An integer specifying the maximum number of parameters expected in 

comimage. 

integer (required) 

The number of parameters found in comimage. 

double array (required) 

A double array of max par ms double -words that, on return, delineates the 
parameters. When the intrinsic is executed, the first numparms double- 
words are returned to the user's process in this array , with the first double - 
word corresponding to the first parameter, the second double-word cor- 
responding to the second parameter, and so forth. The parameter fields of 
comimage are delimited by the delimiters specified in delimiters. In for- 
matting , the byte pointer in the first word of params points to the parame- 
ter in comimage. The string in comimage is upshifted. The second word of 
params contains the delimiter number and parameter information. Each 
double-word in the array named by params contains the following 
information : 

Word 1 : Contains the byte pointer to the first character of the parameter. 
If the parameter is empty or all blanks, the pointer indicates the location of 
the delimiter. 

Word 2 : Contains bits that describe the parameter : 

Bits (11:5) - 

The zero-relative position of the delimiter in delimiters. For example, if 
the default delimiters array is used , and the current parameter is delimited 
by a semicolon, this field will contain 2. 

Bit (10:1) - Special characters indicator bit. 
This bit may be set as follows : 

=0 The parameter contains no special characters. 

= 1 The parameter contains special characters other than those listed in 
delimiters. 

Bit (9:1) - Numeric character indicator bit. 
The settings for this bit are as follows: 

=0 The parameter does not contain numeric characters. 

= 1 The parameter contains numeric characters. 

Bit (8:1) - Alphabetic characters indicator bit. 
This bit may be set as follows : 

=0 The parameter does not contain alphabetic characters. 

= 1 The parameter contains alphabetic characters. 

Bits (0:8) - These bits contain the length of the parameter in bytes. 
This value is zero if the parameter is omitted. 
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diet byte array (optional) 

A byte array that will be searched for the command name in comimage. 
The format must be identical to that of the diet parameter in the SEARCH 
intrinsic. Actually, the command, delimited by a blank, is extracted from 
comitnage, and the SEARCH intrinsic is called with the command name used 
as the target parameter in SEARCH. If the command name is found in diet, 
its entry number is returned to the user's program . If the command is not 
found, or if the diet parameter is not specified, zero is returned. If diet is 
specified but the command name is not found in diet, the parameters 
specified in comimage are not formatted. 

Default : is returned . 

defn byte pointer (optional) 

A word to which the relative address of the definition portion of the com- 
mand entry in diet is returned . 

Default: The corresponding information is not returned. 

CONDITION CODES 

CCE The parameters were formatted, without exception. If diet was specified, 

the command entry number was returned to the user's program . 

CCG More parameters were found in comimage than were allowed by maxparms. 

Only the first maxparms of these parameters were formatted in params and 
returned to the user. 

CCL The diet parameter was specified, but the command name was not located 

in the array diet. The parameters in comimage were not formatted. 

ADDITIONAL DISCUSSION 

"Formatting Command Parameters" in Section V. 
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OPENLOG 

INTRINSIC NUMBER 210 



Provides access to the user logging facility. 

SYNTAX 



D LA LA I I 

OPENLDG (index, logid ,pass , mode 3 status ) ; 



The OPENLOG intrinsic provides access to the user logging facility. Effective with version G.02.00, 
the number of users and log entries are independent of the number of times OPENLOG is called. There 
must already be an active process for this logging identifier. If the process is active, it will get an 
entry in the logging buffer. Previously each call to OPENLOG obtained an entry and incremented the 
user count in the logging buffer table. This occurred whether or not the user already had an entry in 
the table. This caused applications to exceed the limit for users per process or log entries prematurely. 

Now a logging buffer entry is obtained and the user count is incremented only if this is the first 
OPENLOG call for this user. A counter is used to keep track of the number of times a user has per- 
formed OPENLOG and CLOSELOG. The counter is incremented for every OPENLOG and decremented 
for every CLOSELOG. This is done to ensure that the entry in LOGBUFF is released only if this is the 
last CLOSELOG call for this user (i.e. counter =0). 



PARAMETERS 

index 



logid 



pass 



mode 



status 



double (required) 

A double-word returned which identifies logging access. The index pa- 
rameter is used to check the validity of subsequent calls to the other user 
logging intrinsics. 

logical array (required) 

An array of up to eight characters which supplies user logging identifica- 
tion. The array contains alphanumeric characters. Arrays of less than 
eight characters must be terminated with a nonalphanumeric character. 

logical array (required) 

An array in which a password associated with the logging identifier by 

using the : GETLQG command is assigned . 

integer (required) 

An integer used to indicate whether or not a process should be suspended if 
a request for service cannot be completed immediately . Enter a zero if you 
want to wait for service ; enter a one if you do not want to wait . 

integer (required) 

One of the following integers that the logging system uses to return infor- 
mation on the status of the intrinsic call to the user : 
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Message No . 





2 
3 

4 

5 
6 

7 

8 

9 

10 

12 

13 

14 

15 

16 



Meaning 

No error occurred for this call . 

User requested NOWAIT mode and the logging process is 
busy. 

Parameter out of bounds in logging intrinsic . 

Request to open or write to a logging process that is not 
running. 

Incorrect index parameter passed to a logging intrinsic. 

Incorrect mode parameter passed to a logging intrinsic . 

User request denied because logging process is suspended . 

Illegal capability. Must have User Logging (LG) and 
System Supervisor (OP) capabilities to use a logging 
intrinsic. 

Incorrect password passed to a logging intrinsic. 

Error occurred while writing to the logging file. 

Invalid DST passed to logging system intrinsic . 

System is out of disc space , logging cannot proceed . 

No more logging entries. 

Invalid access to logging file . 

End-of-file on user logging file. 

Invalid logging identifier. 



CONDITION CODES 

The condition code remains unchanged. 

SPECIAL CONSIDERATIONS 

User Logging (LG) and System Supervisor (OP) capabilities required. 

ADDITIONAL DISCUSSION 

"User Logging" in Section III. 
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PAUSE 

INTRINSIC NUMBER 45 



Suspends calling process for a specified number of seconds. 

SYNTAX 



R 
PAUSECintenxzZ); 



PARAMETERS 

interval real (required) 

A positive real value specifying the amount of time, in seconds, that the 
process will pause. The maximum time allowed is approximately 
2,147,484 seconds (almost 25 days). 

CONDITION CODES 

CCE Request granted. 

CCG Request denied because of insufficient system table (Timer Request List) 

space. 

CCL Request denied because a negative value was specified for interval or the 

value is too large. 

ADDITIONAL DISCUSSION 

"Suspending the Calling Process" in Section V. 
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PRINT 

INTRINSIC NUMBER 65 



Prints character string on job/session listing device. 

SYNTAX 



LA IV IV 
PR I NT (message , length , control ) ; 



You can write a string of ASCII characters from an array to the job/session listing device by using the 
PRINT intrinsic. This is similar to issuing an FWR I TE intrinsic call against the file $STDLIST. The 
PRINT intrinsic is limited in its usefulness, however, in that the full capability of the file system is 
not available to a user of this intrinsic. For example, :FILE commands are not allowed and certain 
file intrinsics cannot be used because the filenum parameter , obtained from the FDPEN intrinsic , is not 
available to normal users of the PR I NT intrinsic. 



PARAMETERS 



message 



logical array (required} 

Contains the character string to be output. 



NOTE 



SPL programmers can avoid warning messages in the compiled 
output by setting a byte array equivalent to a logical array for 
the message parameter. 



length 



control 



integer by value (required) 

An integer denoting the length of the character string to be transmitted. If 

length is positive, it specifies the length in words; if length is negative, it 

specifies the length in bytes. Note that if length exceeds the configured 

record length of the device, successive records will be written only on 

terminals. 

integer by value (required) 

An integer representing a Carriage Control Code as shown in Table 2-5, 
"Carriage Control Directives", found in the description of the FWRITE 
intrinsic . 



CONDITION CODES 

CCE Request granted . 

CCG End-of-data was encountered. 

CCL 



Request denied because of input/output error. Further error analysis 
through the FCHECK intrinsic is not possible . 
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ADDITIONAL DISCUSSION 

"Writing Output to the Job/Session List Device" in Section V. 
Point -to-Point Workstation I/O Reference Manual (30000-90250). 
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PRINTFILEINFO 

INTRINSIC NUMBER 21 
Prints a file information display on job/session list device . 

SYNTAX 



IV 
PR I NTF I LE I NFOC/hwm) ; 



From SPL (only), a secondary entry point is provided that allows the PRINTFILEINFD intrinsic to be 
called in the following format : 



IV 
PRINT'FILE'INFOC/Vnm?); 



The PRINTFILEINFD intrinsic causes MPE to print a file information display on the standard list 
device in one of two formats. (Refer to Appendix A.) 

PARAMETERS 

from integer by value (required) 

A word containing the file number. 

CONDITION CODES 

The condition code remains unchanged . 

ADDITIONAL DISCUSSION 

"Writing a File System Error-Check Procedure" in Section IV. 
Point -to -Point Workstation I/O Reference Manual (3O00O-9O2SO). 
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PRINTOP 

INTRINSIC NUMBER 66 



Prints a character string on the System Console. 

SYNTAX 



LA IV IV 

PRINTOP (message s length, control ) ; 



The PRINTOP intrinsic transmits a string of ASCII characters from an array in your program to the 
System Console . 



PARAMETERS 

message 

length 

control 



logical array (required) 

The array from which the character string is output. The character string 
contained in message is limited to 56 characters. Non video enhancing es- 
cape sequences are stripped out. 

integer by value (required) 

An integer denoting the length of the output string to be transmitted. If 
length is positive , it specifies the length in words ; if length is negative , it 
specifies the length in bytes. 

integer by value (required) 
The value or %320. 



NOTE 



If a null character (%000) is embedded in an array to be printed 
on the System Console via PRINTDP, then PRINTOP prints only 
the portion of the array before the null character , regardless of 
the length specified . 



CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL 



Request denied because of a physical input/output error. Further error 
analysis through the FCHECK intrinsic is not possible . 



ADDITIONAL DISCUSSION 

"Writing Output to the System Console" in Section V. 
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PRINTOPREPLY 

INTRINSIC NUMBER 67 
Prints a character string on the System Console and solicits a reply . 

SYNTAX 



I LA IV IV LA IV 

Igth : s PRIHTQPREPLY (message ,lerigth , zero } reply >expectedl )) 



The PRINTOPREPLY intrinsic transmits a string of ASCII characters from an array in your program to 
the System Console and solicits a reply . While the reply is pending , the string can be viewed by using 
the : RECALL command. 



FUNCTIONAL RETURN 



Igth 



integer (optional) 

A positive integer indicating the length of the reply from the System 
Operator. This length represents a word count if expectedl is positive or a 
byte count if expectedl is negative . 

If expectedl is zero, then the PRINTOPREPLY intrinsic behaves like 
PRINTOP and does not solicit a reply. In this case, the value returned by 
PRINTOPREPLY is zero. 

If an error occurs, the value returned is zero. 

The parameter length may be zero , in which case only the standard message 
prefix is written on the System Console. If both length and expectedl are 
zero , then CCL is returned . 



PARAMETERS 

message 
length 



zero 



reply 



logical array (required) 

The array from which the characters are output to the System Console. 

The character string is limited to 50 characters. 

integer by value (required) 

An integer denoting the length of the output string to be transmitted. If 
length is positive, it specifies the length in words; if length is negative, it 
specifies the length in bytes. This parameter should never specify a length 
of more than 50 bytes. 



integer by value (required) 

This parameter is not used by MPE but it must be specified . 

assigned the value of zero. 



Typically it is 



logical array (required) 



The array 
Console . 



y {renuireu/ 

into which the input characters are read from the System 
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expectedl integer by value (required) 

An integer specifying the maximum length of the message to be read into 
the array reply. If expectedl is positive, it specifies a word count; if it is 
negative, it specifies a byte count. This parameter should never specify a 
reply length of more than 31 bytes. 

CONDITION CODES 

CCE Request granted . 

CCG Not returned by this intrinsic. 

CCL Request denied because a physical input/output error occurred. Further 

error analysis through the FCHECK intrinsic is not possible. 

ADDITIONAL DISCUSSION 

"Writing Output to the System Console and Requesting a Reply" in Section V. 
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PROCINFO 

INTRINSIC NUMBER III 
Provides access to process information . 

SYNTAX 



0-V I I IV I BA 

PRDC I NFOCerrorl , error2 ,pin I , itemrwml , iteml ] 

[ , itermum2 , item2 ] 
[ , itemraanZ „ itemZ ] 
[ t itemnum4 , item4 ] 
[ , itermumS , item5 ] 
[ , itemnumB , itew6 ] ) ; 



PARAMETERS 

errorl 

error2 
pin 



itermum 



item 



integer (required) 

An integer indicating the success or failure of the intrinsic call as described 

in Figure 2-4. 

integer (required) 

An integer which supplies additional information concerning an error 

reported in error 1 as described in Figure 2-4. 

integer by value (required) 

An integer specifying the Process Identification Number (PIN) for which 
information is to be returned. A pin value of zero will return information 
about the calling process. This parameter is not compatible with the pin 
parameter of the GETPROCINFO intrinsic. 

integer (optional) 

An integer containing the item number (in any order) of an information 
option as defined in Figure 2-5. The user may request up to 6 options to 
be returned. 

byte array (optional) 

Arrays (in the same order as the itemnums) of returned information as 

specified in Figure 2-5. 



The parameters err or I, error 2, and pin are required. The itemnum and item parameters are optional. 
The actual number included depends upon the information desired. The itemnums and the items are 
paired such that the nth itemnum corresponds to the nth item. An Itemnum contains the option 
number of the desired information. The information is returned in the corresponding item or is stored 
using the item element as a pointer, depending on the information desired. See Note 3 in Figure 2-5 
for the user capabilities required for the use of any option. 
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CONDITION CODES 

CCE Successful call. All error codes set to zero. 

CCG Not used. 

CCL Unsuccessful call with error codes set accordingly. 

ADDITIONAL DISCUSSION 

None. 



Error 1 




1 

2 
3 

4 
5 
6 

7 
8 



Note 1 : 



Note 2: 



Meaning 



Successful execution - no error . 

Insufficient capability to return 
request information. 

Omission of required parameter. 

Required parameter address (other 
than "error 1") out of bounds. 

Illegal array size. 

Invalid itemft. 

Invalid PIN - no information 
returned. 

Unassigned PIN. 

Unpaired itemnum/item parameters. 



Error2 



Index of offending itemnutn. 



Not used. 

Array size passed to PROCINFO. 
Index of offending itemnum . 

-1 

-1 

Index of offending itemnum/item 
pair. 



The process will abort if error I parameter address is illegal or if the intrinsic is 
called in split -stack mode. 

If an error condition is detected while processing an information request, the in- 
dex of the itemnum where the offending option was located is stored in error 2. 



Figure 2-4. Error Codes Returned From PROCINFO 
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ITEM# 



INFORMATION RETURNED 



Ignored. 

1 Process Identification Number of calling process. 

•? Process Identification Number of the father of 

the specified process. 

Number of sons ol the specified process (direct 
descendants). 

Number of descendants (both direct and in- 
direct) of the specified process. 

Number of generations (number of levels in the 
process tree substructure) the specified 
process has including itself. 

Process Identification Numbers of all sons 
(direct descendants). 

Process Identification Numbers of all descen- 
dants (both direct and indirect). 

Priority number in the Master Queue of 
specified process. 

State and activation information of the 
specified process. 

10 Program name where the specified process is 

currently executing. 



Note 1: 



Note 2: 



Note 3: 



ITEM 



Ignored. 

Integer where PIN will be returned. 

Integer where PIN will be returned. (See Note 3.) 



Integer where the number of sons will be 
returned. (See Note 3.) 

Integer where the number of descendants will 
be returned. (See Note 3.) 

Integer where number of generations will be 
returned. (See Note 3.) 



Integer array where son PINs will be returned. 
(See Note 1, 3.) 

Integer array where descendent PINs will be 
returned. (See Note 1, 3) 

Integer where priority will be returned (same as 
Word 1 of GETPROCINFO intrinsic). 

Logical where information will be returned 
(same as Word 2 of GETPROCINFO intrinsic). 

Byte array where the fully qualified program 
name will be stored. (See Note 2, 3.) 



Options 6/7 return a variable number of PINs. In these cases item should be set by the calling 
process to point to an integer where the PINs will be returned. The first word of the array should be 
set by the calling process to indicate the array size in words and the array size should include the 
array size word (i.e. if the user desires four pins, the first entry that contains the array size should 
be 5). PINs will be stored into the array, one PIN per word, starting with the second word and con- 
tinuing until the array is filled or all PINs have been returned. If the array is not filled, the remaining 
unused locations will be padded with zeros. 

The byte array for the program name must be a minimum of 28 bytes long. The name will be 
returned in the form of "f.g.a" where "f" will be the local file name, "g" will be the group name, and 
"a" will be the account name of the file containing the program that the specified process is current- 
ly executing. The name will be returned left -justified with the unused locations filled with blanks. 
If the calling process is executing in Privileged Mode, requests for information will be honored for any 
process. Otherwise, requests will be honored as follows: 

1. Complete information will be returned for sons of the calling process itself. 

2. Item 10 will be returned only if the calling process has read access to the program file. 

3. Information returned for indirect descendants and processes directly above the calling process 
will be limited to items 2 through 7 and 10 only. 

Process Handling capability will also be required for any user mode call unless the calling process 
is requesting information about itself. ^ 



Figure 2-5. Information Options For PROCINFO 
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PROCTIME 

INTRINSIC NUMBER 42 



Returns the accumulated CPU time for a process. 

SYNTAX 



D 
time := PROCTIME; 



The PROCTIME intrinsic is used to obtain the amount of CPU time, in milliseconds, that a process has 
accumulated. This is the basis on which CPU time is charged. (Refer to the : REPORT command in 
the MPE V Commands Reference Manual (32033-90006) for additional information.) 

FUNCTIONAL RETURN 

time double (optional) 

A double integer value which shows the number of milliseconds that the 
process has been running. 

CONDITION CODES 

The condition code remains unchanged . 

ADDITIONAL DISCUSSION 

"Obtaining Process Run Time" in Section V. 
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PTAPE 

INTRINSIC NUMBER 191 
Copies input from paper tapes which do not contain X-OFF control characters to a disc file. 

SYNTAX 



IV IV 

PTtoPEQf ilemml,fUeman2) ; 



When using terminals with attached tape readers (such as the ASR-33), you can read data program - 
matically from paper tapes not containing the X-OFF control character, or from tapes being read 
through terminals not recognizing this character, by using the PTAPE intrinsic. PTAPE deletes the 
characters as the tape is read through a terminal which does not recognize these characters. 

Tape input terminates when a Y character is encountered , returning control to you at the terminal . 

Prior to calling this intrinsic, be sure to position the end -of -file pointer in the disc file (filenum2) to 
the proper position in the file. If you are reading more than one tape, you should specify, in the 
FOPEN intrinsic call that opens the disc file, the append -only aoption and a variable -length record 
format, before the first PTAPE call. In addition, set the end-of-file pointer to zero, if necessary, 
before issuing the first PTAPE intrinsic call. 

Lines will be folded at 256-character intervals until a carriage -control character indicates the end of 
a line or until the input is terminated by the Y character. 

PARAMETERS 

filenuml integer by value (required) 

A word supplying the file number of the user's terminal . This is the value 
returned by FOPEN when the terminal file was opened. 

fileman2 integer by value (required) 

A word supplying the file number of the disc file to which the data is to be 
written. 

CONDITION CODES 

CCE Request granted. 

CCG Request denied because an error occurred while writing to the specified disc 

file. 

CCL Request denied because the input file specified is not a terminal or does not 

belong to the calling process , or because insufficient resources , such as disc 
space or main memory, are available to satisfy the request. (PTAPE 
requires 128 contiguous sectors of work area on Idevl .) 
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SPECIAL CONSIDERATIONS 

Split -stack calls permitted. 

ADDITIONAL DISCUSSION 

Appendix B, "DEVICE CHARACTERISTICS". 

Point-to-Point Workstation I/O Reference Manual (30000-90250). 
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PUTJCW 

INTRINSIC NUMBER 85 



Assigns the value of a particular Job Control Word (JCW) in the JCW Table. 

SYNTAX 



BA L I 
PUTJCW ijcaname, jciwalue 3 statns ) ; 



The PUTJCW intrinsic assigns a specified value to a Job Control Word (JCW) in the JCW Table. If an 
entry of the same name already exists in the table, only its value is entered. If no entry exists for this 
name, an entry is created and its value is entered. 



PARAMETERS 

jcwname 



jcaodlue 



status 



byte array (required) 

A byte array containing the name of the JCW. This array may contain up 
to 255 characters, beginning with a letter and ending with a nonal- 
phanumeric character such as a blank. An "@" causes all executing JCWs 
to be set to jcwvalue. 

logical (required) 

A word containing the value of the JCW. 

integer (required) 

A word used by the system to return a value denoting the execution status 

of the intrinsic, as follows: 

Successful execution. Value entered in JCW . 

1 Error, jcwname greater than 255 characters long. 

2 Error, jcwname does not start with a letter. 

3 Error, JCW table overflow. No JCW with this name exists in table and 
unable to create new entry. 

4 Error, attempted to assign a value to an MPE-defined JCW-value 
mnemonic (OK, WARN, FATAL, or SYSTEM). 

5 Error, cannot assign a value to a system -reserved JCW. 

Value 5 will only be returned if the fundamental operating software is ver- 
sion G. 00. 00 or later. 



SPECIAL CONSIDERATIONS 

There are three types of JCWs in the system; user -defined JCWs, system -defined JCWs, and system - 
reserved JCWs. Attempts to assign a value to a system -reserved JCW will result in an error. The 
system-reserved JCWs are HPDATE, HPDAY, HPHOUR, HPMONTH, HPMINUTE, and HPYEAR. 
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CONDITION CODES 

The condition code remains unchanged. 

ADDITIONAL DISCUSSION 

"User-Defined Job Control Words" in Section V. 
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QUIT 

INTRINSIC NUMBER 76 
Aborts a process. 

SYNTAX 



IV 
QUIT Cram}-, 



From within any process in a user program structure, you can abort the process by using the QUIT 
intrinsic. The QUIT intrinsic also transmits an abort message to the calling process output device, and 
sets the job/session in an error state. In batch jobs not containing the : CONTINUE command this 
results in job termination. For additional information refer to the MPE V Commands Reference 
Manual (32033-90006). 

PARAMETERS 

man integer by value (required) 

Any arbitrary number. When the QUIT intrinsic is executed, num. is 
transmitted as part of the abort message , as follows : 

ABORT :PRDG. GROUP. ACCT . XSEG . %L0C 
PROGRAM ERROR : PROCESS QUIT. PARAM«num 

If «um=0, PARAM=ra#n is not printed. 

CONDITION CODES 

The condition code remains unchanged. 

SPECIAL CONSIDERATIONS 

Split -stack calls permitted. 

Affects the system Job Control Word. 

ADDITIONAL DISCUSSION 

"Aborting a Process" in Section V. 
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QUITPROG 

NO INTRINSIC NUMBER ASSIGNED 



Aborts the entire user process structure. 

SYNTAX 



IV 
QUITPRDG(mon); 



This intrinsic destroys all sons of the job/session main process. The job/session main process is set in 
the error state. In batch jobs not containing the : CONTINUE command this terminates the job. Refer 
to the MPE V Commands Reference Manual (32033-90006) for additional information. 

An abort message is transmitted to the job/session list device. 



PARAMETERS 



num 



integer by value (required) 

Any arbitrary number. When the QUITPROG intrinsic is executed, num. is 

output as part of the abort message , as follows : 

ABORT : PROG . GROUP . ACCT . %SEG . %L0C 
PROGRAM ERROR : PROCESS QUIT. PARAM=n«m 

If num=0, PARAM==nwmis not printed. 



CONDITION CODES 

The condition code remains unchanged. 

SPECIAL CONSIDERATIONS 

Split-stack calls permitted. 

Affects the system Job Control Word. 

ADDITIONAL DISCUSSION 

"Aborting a Program" in Section V. 
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READ 

INTRINSIC NUMBER 64 
Reads an ASCII string from $STDIN into an array. 

SYNTAX 



I LA IV 

Igth : =REPiD(message , expected! ) ; 



This intrinsic is similar to issuing an FREAD intrinsic call against the file SSTDIN. The READ intrinsic 
is limited in its usefulness, however, in that the full capability of the file system is not available to a 
user of this intrinsic. For example, :FILE commands are not allowed and certain file intrinsics can- 
not be used because the filenum parameter, obtained from the FOPEN intrinsic, is not available to 
normal users of the READ intrinsic . 

Basic line editing such as cancellation of lines and backspacing are performed automatically by the in- 
put/output driver. If the input device is a terminal in full -duplex mode with the echo facility on, or 
if the terminal is in half -duplex mode, the characters read are printed. 

READ differs from READX in how it interprets an end-of-file. READ reads a record and if there is a 
colon in the first column end-of-file is set. 



FUNCTIONAL RETURN 

Igth 



integer (optional) 

A positive integer value representing the length of the ASCII string which 
was read. If expected! is positive, the length specified is words; if expectedl 
is negative, the length specified is bytes. 



PARAMETERS 



expectedl 



logical array (required) 

The array into which the ASCII characters are read . 

integer by value (required) 

An integer specifying the maximum length of the message array. If expec- 
tedl is positive , it specifies the length in words ; if expectedl is negative , it 
specifies the length in bytes. When the record is read the first expectedl 
characters are input. If expectedl equals or exceeds the size of the physical 
record, the entire record is transmitted. 
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CONDITION CODES 

CCE Request granted . 

CCG A record with a colon in the first column, signaling the end -of -data or a 

hardware end -of -file was encountered. 

CCL Request denied because a physical input/output error occurred. Further 

error analysis through the FCHECK intrinsic is not possible . 

ADDITIONAL DISCUSSION 

"Transmitting Program Input/Output from Job/Session Input/Output Devices" in Section V. 
Point-to-Point Workstation I/O Reference Manual (30000-90250). 
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READX 

NO INTRINSIC NUMBER ASSIGNED 
Reads an ASCII string from SSTDINX into an array. 

SYNTAX 



I LA IV 

Igth : =READX (message , expected! ) ; 



This intrinsic is similar to issuing an FREAD intrinsic call against the file $STDINX. The READ intrin- 
sic is limited in its usefulness, however, in that the full capability of the file system is not available to 
a user of this intrinsic . For example , : F I LE commands are not allowed and certain file intrinsics 
cannot be used because the filenum parameter , obtained from the FOPEN intrinsic , is not available to 
normal users of the READ intrinsic. 

Basic line editing such as cancellation of lines and backspacing are performed automatically by the in- 
put/output driver. If the input device is a terminal in full -duplex mode with the echo facility on, or 
if the terminal is in half -duplex mode, the characters read are printed. 

READX differs from READ in how it interprets an end -of -file. READX interprets :E0D, :EDF:, or in a 
job, :E0J, : JOB, or :DATA as an end -of -file indication. 



FUNCTIONAL RETURN 



Igth 



integer (optional) 

A positive integer value representing the length of the ASCII string which 
was read. If expectedl is positive, the length is specified in words; if expec- 
tedl is negative , the length is specified in bytes. 



PARAMETERS 

message 
expectedl 



logical array (required) 

The array into which the ASCII characters are read. 

integer by value (required) 

An integer specifying the maximum length of the message array. If expec- 
tedl is positive, the length is specified in words; if expectedl is negative, the 
length is specified in bytes. When the record is read the first expectedl 
characters are input . If expectedl equals or exceeds the size of the physical 
record, the entire record is transmitted. 
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CONDITION CODES 

CCE Request granted. 

CCG An :E0D, :EDF:, or in a job, :EQJ, :JOB, or :DATA command was 

encountered. 

CCL Request denied because a physical input/output error occurred. Further 

error analysis through the FCHECK intrinsic is not possible. 

ADDITIONAL DISCUSSION 

"Transmitting Program Input/Output from Job/Session Input/Output Devices" in Section V. 
Point-to-Point Workstation I/O Reference Manual (30000-90250). 
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RECEIVEMAIL 

INTRINSIC NUMBER 108 
Receives mail from another process. 

SYNTAX 



L IV LA LV 

status : =RECEI VEMA I L (pin, Zocat ion, lAxit/tagO ; 



A process collects mail transmitted to it by its father or a son by using the RECEIVEMAIL intrinsic. If 
the mailbox for the receiving process is empty, the action taken depends on the wait flag parameter 
specified in the RECEIVEMAIL intrinsic call. If the mailbox is currently in use by other intrinsics, the 
RECEIVEMAIL waits until the mailbox is free before accessing it. 



FUNCTIONAL RETURN 

status 



logical (optional) 

One of the following mailbox status codes : 



Status 
Returned 



1 

2 
3 



Meaning 

The mailbox was empty and wait flag bit ( 1 5 : 1 )=0. 

No message was collected because the mailbox contained 
outgoing mail from the receiving process . 

The message was collected successfully . 

An error occurred because an invalid pin was specified 
or a bounds check failed . 

The request was denied because waitflag specified that 
the receiving process wait for mail if the mailbox is 
empty, but the other process sharing the mailbox is al- 
ready suspended, waiting for mail. If both processes 
were suspended, neither could activate the other, and 
they may be deadlocked. 



PARAMETERS 

pin 
location 



integer by value (required) 

An integer specifying the process sending the mail. If a son process is 
specified, the integer is the Process Identification Number (PIN) of that 
process . If a father process is specified , the integer is zero . 

logical array (required) 

The array (buffer) in the stack where the message is to be written. 
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Waitflag logical by value (required) 

A word which specifies the action to be taken if the mailbox is empty. This 
is determined by the setting of bit (15:1). Bit (15:1) has the following 
settings : 

=0 Return immediately to the calling process. 

= 1 Wait until incoming mail is ready for collection. 

CONDITION CODES 

CCE Request granted. The mail was collected (value 2 is returned to status) or 

the mail was not collected because the mailbox contained outgoing mail 
from the receiving process (value 1 is returned to status) . 

CCG Request denied because of an illegal pin parameter (value 3 is returned to 

status). 

CCL Request denied because the bounds check revealed that the location param- 

eter did not define a legal stack address (value 3 is returned to status) or 
because both sending and receiving processes would be awaiting incoming 
mail causing a deadlock (value 4- is returned to status) . 

SPECIAL CONSIDERATIONS 

Process Handling (PH) capability required. 

ADDITIONAL DISCUSSION 

"Interprocess Communication" in Section III. 
DSN/DS Reference Manual (32190-90001). 
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RESETCONTROL 

INTRINSIC NUMBER 55 

Resets terminal to accept CONTROL-Y signal. 

SYNTAX 



RESETCONTROL; 



The RESETCONTROL intrinsic is used to reset a terminal so it can accept a CONTROL-Y signal. To 
take effect, this intrinsic may be called at any time from any procedure, after the CONTROL-Y trap 
has been invoked. 

CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied because the trap procedure was not invoked. 

ADDITIONAL DISCUSSION 

"CONTROL-Y Traps" in Section V. 

Point-to-Point Workstation I/O Reference Manual (30000-90250). 
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RESETDUMP 

INTRINSIC NUMBER 79 



Disables the abort stack analysis facility. 

SYNTAX 



RESETDUMP; 



CONDITION CODES 

CCE Request granted. 

CCG Abort stack analysis facility was disabled prior to the RESETDUMP call and 

remains disabled. 

CCL Not returned by this intrinsic. 

ADDITIONAL DISCUSSION 

MPE Debug/Stack Dump Reference Manual (30000-90012). 
MPE V Commands Manual (32033-90006). 
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SEARCH 

INTRINSIC NUMBER 70 



Searches an array for a specified entry or name . 

SYNTAX 



I 0-V BA IV BA BP 

entryno : =SE(\RCr\ttarget ^length ,dict ,defn} ; 



The SEARCH intrinsic searches a specially formatted array, consisting of sequential entries, for a 
specified name. A simple linear search is performed, with the specified name compared against each 
entry of the specially formatted array. Because the search is linear, the most frequently used name 
byte arrays should appear at the beginning of the array to insure efficient searching. 



FUNCTIONAL RETURN 



entryno 



integer (optional) 

The entry number of the word in diet which matches target. If the name 

specified in target is not found, a zero is returned. 



PARAMETERS 

target 

length 
diet 

defn 



byte array (required) 

Contains the name for which the search is to be performed . 

integer by value (required) 

An integer specifying the length, in bytes, of the byte array target. 

byte array (required) 

The specially formatted array which is to be searched for target. 

byte pointer (optional) 

A word to which the address of the definition portion of the entry sought 

in the array is returned. 

Default: If defn is omitted, the address is not returned. 



CONDITION CODES 

The condition code remains unchanged . 

ADDITIONAL DISCUSSION 

"Searching Arrays" in Section V. 
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SENDMAIL 

INTRINSIC NUMBER 107 



Sends mail to another process. 

SYNTAX 



L IV IV LA LV 

status : 'SE^IX^lLCpintCoimtylocation^ixzit flag")-, 



A process sends mail to its father or sons by using the SENDMAIL intrinsic. If the receiving process 
mailbox contains an uncollected message from the calling process, the action taken depends on the 
wait flag parameter specified in the SENDMAIL intrinsic call. If the mailbox currently is being used by 
other intrinsics , the SENDMA I L intrinsic waits until the mailbox is free and then sends the mail . 

FUNCTIONAL RETURN 



status logical (optional) 

One of the following status codes indicating the success of the intrinsic : 

Status 

Returned Meaning 

The mail was transmitted successfully. The mailbox 
contained no previous mail . 

1 The mail was transmitted successfully. The mailbox 
contained mail sent previously that was overwritten by 
the new mail, or contained previous incoming/outgoing 
mail that was cleared . 

2 The mail was not transmitted successfully because the 
mailbox contained incoming mail to be collected by the 
sending process (regardless of the wait flag setting). 

3 An error occurred because an illegal pin parameter was 
specified , or a bounds check failed . 

4 An illegal wait request would produce a deadlock . 

5 The request was denied because count exceeded the max- 
imum mailbox size allowed by the system . 

6 The request was denied because storage resources for the 
mail data segment were not available . 
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PARAMETERS 

pin integer by value (required) 

An integer specifying the process to receive the mail. If a son process is 
specified, the integer is the Process Identification Number (PIN) of that 
process. If a father process is specified, the integer is zero. 

count integer by value (required) 

An integer specifying the length of the message, in words, transmitted 
from the stack of the sending process. If zero is specified, SENDMAIL 
empties the mailbox of any incoming or outgoing mail. 

location logical array (required) 

The array (buffer) in the stack containing the message. 

Oaitflag logical by value (required) 

A word specifying in bit (15:1) the action to be taken if the mailbox con- 
tains previously sent mail. Bit (15:1) has the following settings : 

=0 Cancel (overwrite) any mail sent previously with the current mail. 

= 1 Wait until the receiving process collects the previous mail before send- 
ing current mail. 

CONDITION CODES 

CCE Request granted. The mail was sent (value or 1 is returned to status) or 

the mail was not sent because the mailbox contained incoming mail to be 
collected by the sending process (value 2 is returned to status). 

CCG Request denied because of an illegal count parameter (value 5 is returned to 

status), an illegal pin parameter was specified (value 3 is returned to 
status) , or storage for the mail data segment was not available (value 6 is 
returned to status). 

CCL Request denied because the bounds check revealed that the count or location 

parameters did not define a legal stack area (value 3 is returned to status), 
or both processes are waiting to send mail (value 4 is returned to status). 

SPECIAL CONSIDERATIONS 

Process Handling (PH) capability required. 

ADDITIONAL DISCUSSION 

"Interprocess Communication" in Section III. 
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SETDUMP 

INTRINSIC NUMBER 78 



Enables the stack analysis facility. 

SYNTAX 




PARAMETERS 

flags 



logical by value (required) 

A logical word whose bits specify the following if set to =1 : 

Bit (1 5: 1) - Specifies a DL to Q initial dump. 

Bit (14:1) - Specifies a Q initial to S dump. 

Bit (13:1) - Specifies a Q-63 to S dump. This bit is ignored if bit 
(14:1)=1. 

Bit (1 2: 1 ) - Causes an ASCII dump of the octal content along with the oc- 
tal values. 

If bits (12:4)=0, flags will specify a display of registers and stack marker 
trace only. 

Bits (0:12) are reserved for MPE. 



CONDITION CODES 

CCE Request granted. 

CCG 



CCL 



Abort stack analysis facility already enabled before SETDUMP call. The 
facility is now set up according to new specifications from this call. 

Not returned by this intrinsic. 



ADDITIONAL DISCUSSION 

MPE Debug/Stack Dump Reference Manual (30000-90012). 
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SETJCW 

INTRINSIC NUMBER 72 
Sets bits in the system Job Control Word , JCW. 

SYNTAX 



LV 
SETJCWCtford) ; 



You can establish the bit contents of the system Job Control Word, JCW, with the SET JCW intrinsic . 

PARAMETERS 

Word logical by value (required) 

A 16 -bit word whose contents are established by the user for Interprocess 
Communication. The form is: 

1 15 







Bit (0: 1) is reserved for MPE and should be set to zero. If you set (0: 1)=1 , 
the system will output the following message when the user program ter- 
minates, either normally or due to an error: 

PROGRAM TERMINATED IN ERROR STATE CCIERR 976) 

In batch mode, the job is terminated unless the : CONTINUE command is 
used. If you set JCW to exactly % 140000 (bits (0:1)=1 and (1:1)=1 only), 
the CI ERR 976 message is replaced by: 

PROGRAM ABORTED PER USER REQUEST CCIERR 989) 

Refer to the MPE V Commands Reference Manual (32033-90006) for a 
discussion of : CONTINUE. Bits (1:15) may be used for any purpose. 



CONDITION CODES 

The condition code remains unchanged. 

ADDITIONAL DISCUSSION 

"User-Defined Job Control Words" in Section V. 
MPE V Commands Reference Manual (32033-90006). 
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STACKDUMP 

INTRINSIC NUMBER 77 



Dumps selected parts of stack to a file. 

SYNTAX 



0-V BA I L DA 

STACKDUMP i filename > idnumber , flags , selec ) ; 



or (from SPL only): 



0-V BA I L DA 

STtoCKD\JltW'Cfileriarr&,idnt#riber } flags, selec)-, 



PARAMETERS 

filename 



idnumber 



flags 



byte array (optional) 

Contains the filename of the file where the information is to be dumped. 
When filename contains the formal designator of the file, the file will be 
opened and closed by the STACKDUMP intrinsic. If the secondary entry 
point STACKDUMP' is used to enter this intrinsic, MPE assumes that 
filename{0) contains the file number of a file which has been successfully 
opened prior to the call to STACKDUMP. In this case, the file is not closed 
before returning to the calling program. When a file number is passed via 
the STACKDUMP' secondary entry point, the record length must be between 
32 and 256 words and write access must be allowed for the file. 

Default: Dump is sent to $STDL I ST. 

integer (optional) 

An integer which is displayed in the header of the dump to identify the 
printout. If this intrinsic is unsuccessful, the value of idnumber is the cor- 
responding file system error number . 

Default: Identifying integer not displayed. 

logical (optional) 

A logical value used to specify the following options : 

Bit ( 1 5 : 1 ) - Controls ASCII dump. 

=0 Provide ASCII dump. 

= 1 Suppress ASCII dump. 
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Bit (14:1) - Controls trace back of stack markers. 

=0 Display trace back of stack marker. 

= 1 Do not display trace back of stack marker. 

Default: If Bits (14:2)=00, a corresponding ASCII dump is provided for all 
values dumped in octal , and a trace back of stack markers is displayed . 

selee double array (optional) 

Specifies which stack areas are to be dumped. The format of the array is 
shown in the MPE Debug/Stack Dump Reference Manual (30000-90012). 
The array has no predetermined length; the first double -word containing 
the values 0/-1 indicates the end of the array. An entry for which the 
count is is interpreted as a "skip" (for example, to next double-word 
element in list). 

Default: If missing, or if the first double-word contains 0/-1 (indicating 
end of array), no dump occurs (except for the header), unless flags bit 
( 1 4 : 1 )=0 , in which case the trace back of stack markers is displayed . 

CONDITION CODES 

CCE Request granted. 

CCG Request denied. Bounds violation occurred and the dump was not com- 

pleted. Record size was not between 32 and 256 words. 

CCL Request denied . File system error occurred during opening , writing to , or 

closing the file. The file error number is returned in idnwnber. 

ADDITIONAL DISCUSSION 

MPE Debug/Stack Dump Reference Manual (30000-90012). 
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STARTSESS 

INTRINSIC NUMBER 195 
Initiates a session on the specified terminal. (Available only on version G.01 .00 and later.) 

SYNTAX 



IV BA I D IA 

STARTSESS (IdeV, logonstr, jsid y jsnum t eivorstat ) ; 



STARTSESS initiates a session on the specified terminal using the given logon string. The terminal on 
which the session is to be created must be available; no other user may be logged on. The target ter- 
minal will not be speed sensed, so it must be set at the configured baud rate. 

When the session is created, nothing will be printed to the terminal until the [RETURN] key is pressed 
unless ; NONA IT is specified. To override the need for a IRETURNI . the ; NOWAIT keyword parameter 
may be entered with the logon string when executing the : STARTSESS command or invoking the 
STARTSESS intrinsic. For example, :STARTSESS 21 ;MANAGER/pqss.SVS;NQUJAIT or passing a byte 
array of "MANAGER/pass.SYS; NOWAIT (%15)" to the STARTSESS intrinsic will start a session and 
logon immediately without waiting for a IRETURNI . The ; NOWAIT parameter should never be used 
without first ensuring that the target terminal is turned on and set at the default baud rate. If the 
target terminal is the System Console and NOWAIT is specified, then the invoker must have System 
Manager (SM) capability. All other valid terminals may be specified by the invoker with only 
Programmatic Sessions (PS) capability. 



PARAMETERS 

Idev 



logonstr 



jsid 



jsman 



integer by value (required) 

The logical device number of the terminal on which the session is to be 
created. This must a real physical device, and it must be a hardwired ter- 
minal. The terminal must be configured as TYPE 1 6 and SUBTYPE or 4. 

byte array (required) 

The character holding the logon parameters in the same format expected in 
the : STARTSESS command. For more details on the : STARTSESS com- 
mand, refer to the MPE V Commands Reference Manual (32033-90006). 
The first characters in the string should be the session name, if specified, or 
the user name if no session name is assigned; logonstr must be terminated 
with a carriage return character (%1 5). 

Passwords must be supplied in the logonstr. There will be no prompting for 
passwords. If passwords are required but not supplied, STARTSESS will 
fail. 

integer (required) 

Indicates the type of Command Interpreter (CI) process. If the STARTSESS 
call was successful , the value returned will be 1 , if unsuccessful , the value 
will be 0. When the value returned to jsid is 1 , jsid and jsnum can be used 
as input to JOB INFO to check on the various attributes of the session. 

double (required) 

A 32-bit value which when used with jsid uniquely identifies the created 

session. 
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ervorstcct integer array (required) 

A two -element array in which the status of the call is returned. The 
second element is reserved for future use, and will always contain a zero. 
The first element will contain a zero if no errors occurred. If an error oc- 
curs one of the following error values is returned in the first element : 

Error No. Meaning 

Successful call . 

7000 The Idev is out of range. 

7001 The Idev must not be virtual. 

7002 The device specified by Idev is not a terminal. 

7003 The Idev is not free . 

7004 The Idev is not job accepting. 

7005 The Idev is in diagnostic mode. 

7006 The Idev terminal is do wn . 

7007 DOWN pending on Idev. 

7008 Logical device specified by Idev is not a real device. 

7009 Caller lacks Programmatic Sessions (PS) capability. 

7014 Session was aborted before logging on. 

7015 Logon failed because system is at its session limit. 

7016 Logon failed because the session's INPRI was less than or 
equal to the system's JDBFENCE. 

7017 Logon failed because the system was unable to obtain a 
PCB entry for the system process. 

7018 Logon failed because the system was unable to obtain a 
DST entry for the session. 

7019 Logon failed because the system was unable to obtain a 
DST entry for the session's JIT. 

7020 Logon failed because the system was unable to obtain a 
DST entry for the session's JDT. 

7021 Logon failed because the system was unable to obtain a 
file DST entry. 

7022 Logon failed because the system was unable to obtain an 
entry in the JPCNT table for the session. 

7023 Logon failed because the system was unable to obtain the 
XDD entry for the output device. 

7024 Logon failed because the system was unable to obtain the 
XDD entry for the input device. 

7025 Unknown error occurred. This would only happen in the 
case of an illegal call from one internal procedure to 
another internal procedure when passing the error 
number . 

7026 Unable to allocate $STDIN or logon failed because of a 
failure to open $STDIN. 

7027 Unable to allocate $STDLIST or logon failed because of a 
failure to open $STDLIST. 

7028 Logon failed because a disconnect was detected on the 
terminal during logon processing . 

7029 Logon failed because the session's account is out of CPU 
time. 

7030 Logon failed because the session's account is out of 
CONNECT time. 
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Error No. Meaning 

7033 Logon failed because the session's logon group is out of 
CPU time. 

7034 Logon failed because the session's logon group is out of 
CONNECT time. 

7042 Group is not specified, and there is no default home 

group. 

1 444 Password is required but not specified in logonstr. 

1424 Missing or invalid user name in logonstr. 

1426 Missing or invalid account name in logonstr. 

1438 No such user in the account. 

1437 No such account in the system. 

1436 No such group in the account . 

1431 Specified session user lacks Interactive Access (IA) 

capability . 

1412 Logon failed due to JMAT overflow. 

1411 Logon failed due to IDD overflow. 

- 1 4 5 8 Bad TERMTYPE specified in logonstr , default used . 

-1459 Invalid PR I specified in logonstr, default used. 

- 1 479 Invalid TIME specified in logonstr, no time limit is used. 

-1461 H I PR I then I NPR I specified , I NPR I used . 

-1464 INPRI then HIPRI specified, HIPRI used. 

- 1 4 6 2 I NPR I too low , lowest valid INPRI used . 

- 1 4 6 3 I NPR I too high , highest valid INPRI used . 

- 1 4 6 5 OUTCLASS specified , ignored . 

- 1 4 7 3 RESTART specified , ignored . 

-1452 Unknown parameter found in logonstr, ignored. 

- 1 4 5 1 Ignored delimiter . 



CONDITION CODES 

The condition code remains unchanged. 

SPECIAL CONSIDERATIONS 

Programmatic Sessions (PS) capability required. 

ADDITIONAL DISCUSSION 

None. 
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SUSPEND 

INTRINSIC NUMBER 103 
Suspends a process. 

SYNTAX 



0-V LV IV 
SUSPEND(swsp,rin); 



A process can suspend itself with the SUSPEND intrinsic. When this intrinsic is executed, the process 
relinquishes its access to the central processor unit until reactivated by an ACTIVATE intrinsic call. 
When a process suspends itself, it must specify the anticipated source of this ACTIVATE call (its father 
or a son process). When the process is reactivated, it begins execution with the instruction immediate- 
ly following the SUSPEND call. 

PARAMETERS 

susp logical by value (required) 

A word whose 1 4th and 1 5th bits specify the anticipated source of the call 
that later will reactivate the process. For processes run by users with only 
the Process Handling (PH) capability, at least one of these bits must = 1 . 

Bit (15:1) - Father activation bit. 

=C Process does not expect to be activated by its father. 

= 1 Process expects to be activated by its father . 

Bit (14:1) - Son activation bit. 

=0 Process does not expect to be activated by one of its sons. 

= 1 Process expects to be activated by one of its sons. 

If (14: 1 )= 1 and (15:1)=1, the suspended process can be activated by either 
father or sons. Bits (0 : 1 4) are reserved by MPE and should be set to zero. 

vin integer by value (optional) 

An integer specifying a Resource Identification Number (RIN). If rin is 
specified, it represents a local RIN that is locked by the process but that 
will be released when this process is suspended. This facility can be used to 
synchronize processes within the same job. 

Default: If omitted, no RIN is unlocked when the process suspends. 
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CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied because the susp parameter is not valid , the specified RIN 

is not owned by this process, or the specified RIN was not locked. 

SPECIAL CONSIDERATIONS 

Split-stack calls permitted . 

Process Handling (PH) capability required. 

ADDITIONAL DISCUSSION 

"Suspending Processes" in Section III. 
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SWITCHDB 

INTRINSIC NUMBER 139 
Switches DB register pointer. 

SYNTAX 



L 0-P LV 

logindex : =SWITCHDBC£ndex) ; 



The SWITCHDB intrinsic changes the DB register so that it points to the base of an extra data segment 
instead of the base of the stack. 

FUNCTIONAL RETURN 

logindex logical (optional) 

The logical index of the data segment indicated by the previous DB register 
setting, thus allowing you to restore this setting later. If the previous DB 
setting indicated the stack , zero is returned . 

PARAMETERS 

index logical by value (required) 

Specifies the logical index of the data segment to which the DB register is 
to be switched , as obtained through the GETDSEG intrinsic call in Privileged 
Mode. MPE checks the value specified for index to ensure that the process 
has acquired access to this segment previously. For an extra data segment, 
index must be a positive, nonzero integer. To switch back to the stack 
segment, index must be zero. 

CONDITION CODES 

CCE Request granted . 

CCG Not returned by this intrinsic. 

CCL Request denied because an illegal data segment was specified . 

SPECIAL CONSIDERATIONS 

The program calling both SWITCHDB and GETDSEG which generated the value for index must be run- 
ning in Privileged Mode. GETDSEG requires Data Segment Management (DS) capability. 

ADDITIONAL DISCUSSION 

"Moving the DB Pointer" in Section HI. 
The GETDSEG intrinsic in this section . 
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TERMINATE 

INTRINSIC NUMBER 60 



Terminates a process. 

SYNTAX 



TERMINATE; 



A process and all of its descendants (sons), including any extra data segments belonging to them, can 
be deleted by using the TERMINATE intrinsic. 

All files still open by the process and its descendants are closed and assigned the same disposition they 
had when opened. 

CONDITION CODES 

The process that calls this intrinsic is terminated and no return is made . 

SPECIAL CONSIDERATIONS 

Split-stack calls permitted. 

ADDITIONAL DISCUSSION 

"Deleting Processes" in Section III and "Terminating a Process" in Section V. 
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TIMER 

INTRINSIC NUMBER 40 
Returns system timer information. 

SYNTAX 



D 

cown t :=T I MER; 



A 3 1 -bit logical quantity representing the current system timer and overflow count can be returned 
to your program with the TIMER intrinsic. 

The resolution of the system timer is one millisecond. Thus, readings taken within a one-millisecond 
period may be identical. 

FUNCTIONAL RETURN 

count double (optional) 

A 31 -bit logical quantity representing the actual millisecond count since 
the midnight preceding the last system coldload . 

CONDITION CODES 

The condition code remains unchanged . 

SPECIAL CONSIDERATIONS 

Split -stack calls permitted. 

ADDITIONAL DISCUSSION 

"Obtaining System Timer Information" in Section V. 
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UNLOADPROC 

INTRINSIC NUMBER 81 



Dynamically unloads a library procedure. 

SYNTAX 



IV 
UNLDADPRDCCproeid); 



The UNLOADPROC intrinsic dynamically unloads a procedure and its referenced external procedures. 

PARAMETERS 

ppocid integer by value (required) 

A word containing the procedure's identity number, which was obtained 
from the LOADPROC intrinsic call. 

CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied because of invalid procid. 

ADDITIONAL DISCUSSION 

"Dynamic Loading and Unloading of Library Procedures" in Section V. 
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UNLOCKGLORIN 

INTRINSIC NUMBER 35 
Unlocks a global RIN. 

SYNTAX 



IV 

UNLOCKGLOR I N Orinnum) ; 



The UNLDCKGLDRIN intrinsic unlocks a global Resource Identification Number (RIN) that has been 
locked with the LOCKGLQRIN intrinsic. 

PARAMETERS 

rinman integer by value (required) 

A word supplying the number of any RIN locked by the calling process. If 
rinnum does not specify a RIN locked by the calling process, no action is 
taken. 

CONDITION CODES 

CCE Request granted. 

CCG Request denied because this RIN was not locked for this purpose. 

CCL Request denied because the specified RIN was not allocated. 

ADDITIONAL DISCUSSION 

"Resource Management" in Section III. 
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UNLOCKLOCRIN 

INTRINSIC NUMBER 33 



Unlocks a local RIN . 

SYNTAX 



IV 
UNLOCKLDCR I N (rinman) ; 



The UNLDCKLDCRIN intrinsic unlocks a local Resource Identification Number (RIN) that has been 
locked by the LOCKLOCR IN intrinsic. 

PARAMETERS 

rinnum integer by value (required) 

A word supplying the locked RIN, designated by an integer from 1 to the 
value specified in the rincount parameter of the GETLOCRIN intrinsic call. 

CONDITION CODES 

CCE Request granted. 

CCG Request denied because the RIN specified is not locked by the calling 

process. 

CCL Request denied because the specified RIN is not allocated to this process. 

ADDITIONAL DISCUSSION 

"Resource Management" in Section III. 
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WHO 

INTRINSIC NUMBER 69 
Returns information about a user. 

SYNTAX 



0-V L D D BA BA BA BA L 

UIHOCmocte, capability >lattr ,usexn ,gr>owpn yCtcct ,homen , term') ; 



The WHO intrinsic supplies the access mode and attributes of the user running the program. 

PARAMETERS 

mode logical (optional) 

A word to which the current user's access mode is returned. In this word, 
the bits have the following meanings: 

Bit (15:1) 

=0 The job/session input file and job/session list file are not interactive. 

= 1 The job/session input file and job/session list file form an interactive 
pair. A dialog can be established between a program, displaying infor- 
mation on the list device, and a person responding through the input 
device. 

Bit (14:1) 

=0 The job/session input file and job/session list file are not duplicative. 

= 1 The job/session input file and job/session list file form a duplicative 
pair. Images on the input device are duplicated automatically on the 
list device. 

Bits (12:2) 

=00 Is not used. 

=01 The user is accessing the system through a session. 

= 10 The user is accessing the system through a job. 

= 11 Is not used. 

Bits (0:12) - Reserved for MPE. The WHO intrinsic sets these bits to zero. 

Default : The user's access mode is not returned . 
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capability double (optional) 

A double -word to which the user's file access, user, and capability class at- 
tributes are returned. In the first word, possession of the following file ac- 
cess and user attributes is indicated by the corresponding bit being = 1 . 

File access attributes : 

Bit (1 5: 1)- Ability to save files (declare them permanent) (SF). 

Bit (14: 1)- Ability to acquire nonsharable devices (ND). 

Bit (13:1 ) -Communications System (CS) . 

Bit (12: l)-Node Manager (NM). (On version G.01 .00 or later.) 

Bit (11:1 ) -Network Administrator (NA). (On version G.01 .00 or later.) 

Bits (9: 2) -Reserved for MPE. The WHO intrinsic sets these bits to zero. 

Bit (8:1)- User Logging (LG). 

Bit (7:1)- Volume set usage (UV). 

Bit (6:1)- Volume set creation (CV). 

User Attributes: 

Bit (5:1)- System Supervisor (OP). 

Bit (4:1)- Diagnostician (DI). 

Bit (3:1)- Group Librarian (GL). 

Bit (2:1)- Account Librarian (AL). 

Bit (1:1)- Account Manager (AM). 

Bit (0:1)- System Manager (SM). 

In the second word, possession of the user's capability -class attributes is in- 
dicated by the corresponding bit being =1 . 

Bit (1 5 :l)-Process Handling (PH). 

Bit (14:l)-Extra Data Segments (DS). 

Bit ( 1 3 : 1 ) -Reserved for MPE. The WHO intrinsic sets this bit to zero. 

Bit (12:l)-MultipleRINs (MR). 

Bit (1 1 : 1) -Reserved for MPE. The WHD intrinsic sets this bit to zero. 

Bit (10: 1) -Programmatic Sessions (PS). (On version G.01 .00 or later.) 
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lattr 



usern 



groupn 



acctn 



homen 



term 



Bit (9:1)- Privileged Mode operation (PM). 

Bit (8:1)- Interactive (session) access (IA). 

Bit (7:1)- Batch (job) access (BA). 

Bit (0:7)- Reserved for MPE. The WHO intrinsic sets these bits to zero. 

Default: The user's file access, user, and capability -class attributes are not 
returned . 

double (optional) 

A double -word to which the local attributes of the user, as defined by a 

user with the Account Manager attribute, is returned. 

Default: The user's local attributes are not returned. 

byte array (optional) 

An 8-byte array to which the user's name is returned. 

Default : The user's name is not returned . 

byte array (optional) 

An 8-byte array to which the name of the user's logon group is returned. 

Default: The user's logon group is not returned. 

byte array (optional) 

An 8-byte array to which the name of the user's logon account is returned. 

Default: The user's logon account is not returned. 

byte array (optional) 

An 8-byte array to which the name of the user's home group is returned. 

If a home group is not assigned, this array is filled with blanks. 

Default: This information is not returned. 

logical (optional) 

A word to which the logical device number of the job/session input device 
is returned. If this is a spooled (: STREAM) batch job, then the logical 
device number will be the virtual device. 

A virtual device simulates a spooling device. The actual spooling device 
cannot be owned by users, so the virtual device allows users access to spool- 
ing. Each virtual device will be temporarily assigned a logical device num- 
ber for the duration of the input or output spooling process. Since the same 
logical device number can be reassigned to another virtual device with dif- 
ferent physical characteristics, such as page length, the virtual device is not 
permanently configured in the system configuration. The logical device 
number of the virtual device can also be obtained with FFILEINFD. 

Default: The logical device number is not returned. 
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CONDITION CODES 

The condition code remains unchanged . 

ADDITIONAL DISCUSSION 

"Determining the User's Access Mode and Attributes" in Section V. 
Point-to-Point Workstation I/O Reference Manual (30000-90250). 
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WHITELUU 

INTRINSIC NUMBER 211 
Writes a record to a logging file . 

SYNTAX 



D LA I I I 

HR I TELOG (.index 3 datct t len t mode , status ) ; 



The WR I TELDG intrinsic journalizes data base and subsystem file additions and modifications to the 
user logging file. 



PARAMETERS 

index 
data 



ten 



mode 



status 



double (required) 

The parameter returned from OPENLOG that identifies your access to the 

logging file. 

logical array (required) 

The array in which the information to be logged is passed. A log record 
contains 128 words of which 119 are available to you. Thus the most effi- 
cient use of log file space is to structure your arrays with lengths in multi- 
ples of 119 words. 

integer (required) 

The length of the data in data. A positive number indicates words, a nega- 
tive number indicates bytes. If the length is greater than 119 words, the 
information in data is divided into two or more physical log records. 

integer (required) 

An integer which you use to indicate whether or not your process should be 
suspended if your request for service cannot be completed immediately. 
Enter a zero if you want to wait for service , enter a one if you do not want 
to wait. If a two is entered it will cause the logging buffer to get written 
to the disc logfile (disc logging) or disc buffer file (serial logging) at the 
first opportunity. This is the only intrinsic that allows a setting for mode 
that is greater than 1 . 

integer (required) 

One of the following integers indicating the success/failure of the call : 

Message No. Meaning 

No error occurred for this call . 



1 



User requested NOW AIT mode and the logging process is 
busy. 

Parameter out of bounds in logging intrinsic . 
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Message No 


3 


4 


5 


6 


7 


8 


9 


10 


12 


13 


14 


15 


16 



Meaning 

Request to open or write to a logging process that is not 
running . 

Incorrect index parameter passed to a logging intrinsic. 

Incorrect mode parameter passed to a logging intrinsic . 

User request denied because logging process is suspended. 

Illegal capability. Must have User Logging (LG) and 
System Supervisor (OP) capabilities to use a logging 
intrinsic . 

Incorrect password passed to a logging intrinsic. 

Error occurred while writing logging file . 

Invalid DST passed to a logging system intrinsic. 

System is out of disc space, logging cannot proceed. 

No more logging entries. 

Invalid access to logging file. 

End-of-file on user log file. 

Invalid logging identifier . 



CONDITION CODES 

The condition code remains unchanged. 

SPECIAL CONSIDERATIONS 

User Logging (LG) and System Supervisor (OP) capabilities required. 

ADDITIONAL DISCUSSION 

"User Logging" in Section IV. 
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XARITRAP 

INTRINSIC NUMBER 50 
Enables or disables the user-written software arithmetic trap. 

SYNTAX 



IV IV I I 

XARITRAP (mxsk s plabel s oldaask 3 oldplabel ) ; 



The XARITRAP intrinsic enables you to replace the trap handler in MPE with your own trap handler 
routine. 

The validity of a trap procedure, specified by the external-type label of the user's trap procedure 
plabel, depends on the code domain of the caller's code and executing mode (privileged or non- 
privileged). The code domains are : 

PROG (User Program) 

GSL (Group SL) 

PSL (Public SL) 

SSL (System SL, non-MPE segments) 

MPESSL (System SL, MPE segments) 

If, when a trap procedure is being enabled, the code of the caller is in one of the following states: 

• Nonprivileged in PROG , GSL , or PSL , plabel must be nonprivileged in PROG , GSL , or PSL. 

• Privileged in PROG, GSL, or PSL, plabel may be privileged or nonprivileged in PROG, GSL, or 
PSL. 

• Privileged or nonprivileged in SSL, plabel may be in any non -MPESSL -segment. 

PARAMETERS 

mask integer by value (required) 

A word mask that selects which hardware traps will invoke the software 
trap, and which will not. Only the 14 right -most bits of the word forming 
the mask are used. The setting of the other bits is not significant, but it is 
recommended that they be set to zero. Thus, octal values up to %3 7 77 7 are 
allowed for this parameter . 

If a bit is on (= 1 ) , the corresponding hardware trap activates the software 
trap. If a bit is off (=0) , the corresponding hardware trap does not activate 
the software trap. If all bits are set to zero, the software trap is disabled. 
Hardware traps are activated by the following relationships : 

Bit Hardware Error Trap 

(15:1) Floating Point Divide By Zero . 

(14:1) Integer Divide By Zero . 

(13:1) Floating Point Underflow . 
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plabel 



oldmask 



oldplabel 



(12:1) 

(11:1) 

(10:1) 

(9:1) 

(8:1) 

(7:1) 

(6:1) 

(5:1) 

(4:1) 

(3:1) 

(2:1) 



Floating Point Overflow. 

Integer Overflow. 

Extended Precision Overflow . 

Extended Precision Underflow. 

Extended Precision Divide By Zero . 

Decimal Overflow. 

Invalid ASCII Digit. 

Invalid Decimal Digit . 

Invalid Source Word Count . 

Invalid Decimal Operand Length . 

Decimal Divide By Zero. 



integer by value (required) 

The external-type label of the user's trap procedure. If the value of this 
entry is 0, the software trap is disabled. The external-type label of the 
procedure, which resides in the segment transfer table of the procedure's 
code segment, is passed as a parameter (in SPL) by placing an £ before the 
procedure name . 

integer (required) 

A word in which the value of the previous mask is returned to the user's 

program . 

integer (required) 

A word in which the previous plabel is returned to the user's program. If 

no plabel existed previously , zero is returned . 



CONDITION CODES 



CCE 
CCG 
CCL 



Request granted. Software trap enabled. 
Request granted. Software trap disabled. 
Request denied because of an invalid plabel. 



ADDITIONAL DISCUSSION 

"Enabling and Disabling Traps" in Section V. 
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XCONTRAP 

INTRINSIC NUMBER 54 
Enables or disables the CONTROL-Y trap. 

SYNTAX 



IV I 

XCONTRAP tplabel 3 oldplabel ) ; 



When a session is initiated, the CONTROL-Y trap is disabled. The XCONTRAP intrinsic enables this 
trap. This intrinsic takes effect on the file $STDINX, and also on $STDIN (when $STDINis defined as 
a terminal) . 

The validity of a trap procedure, specified by the external-type label of the user's trap procedure 
(plabel), depends on the code domain of the caller's code and executing mode (privileged or non- 
privileged). The code domains are: 

PROG (User Program) 

GSL (Group SL) 

PSL (Public SL) 

SSL (System SL, non-MPE segments) 

MPESSL (System SL, MPE segments) 

If, when a trap procedure is being enabled, the code of the caller is one of the following states: 

• Nonprivileged in PROG, GSL, or PSL, plabel must be nonprivileged in PROG, GSL, or PSL. 

• Privileged in PROG, GSL, or PSL, plabel may be privileged or nonprivileged in PROG, GSL, or 
PSL. 

• Privileged or nonprivileged in SSL, plabel may be in any non -MPESSL segment. 

PARAMETERS 

plabel integer by value (required) 

The external -type label of the user's trap procedure. If the value of this 
entry is , the software trap is disabled . 

oldpldbel integer (required) 

A word in which the previous plabel is returned to the user's program. If 
no plabel existed previously, zero is returned. 

CONDITION CODES 

CCE Request granted . Trap enabled. 

CCG Request granted. Trap disabled . 

CCL Request denied because of illegal plabel, or because $STDIN is not defined 

as a terminal. 
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ADDITIONAL DISCUSSION 

"Enabling and Disabling Traps" in Section V. 

Point-to-Point Workstation I/O Reference Manual (30000-90250). 
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XLIBTRAP 

INTRINSIC NUMBER 52 
Enables or disables the software library trap. 

SYNTAX 



IV I 

XL IBTRbP (.plabel y oldplabel ) ; 



When a program begins execution, the software library trap is disabled automatically. You can en- 
able (or subsequently disable) this trap with the XLIBTRAP intrinsic call. 

PARAMETERS 

plabel integer by value (required) 

The external -type label of the user's trap procedure. If the value of this 
entry is 0, the trap is disabled. 

oldplabel integer (required) 

A word in which the previous plabel is returned to the user's program. If 
no plabel existed previously, zero is returned. 

CONDITION CODES 

CCE Request granted. Trap enabled. 

CCG Request granted. Trap disabled . 

CCL Request denied because of an illegal plabel. 

ADDITIONAL DISCUSSION 

"Enabling and Disabling Traps" in Section V. 
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XSYSTRAP 

INTRINSIC NUMBER 53 



Enables or disables the system trap. 

SYNTAX 



IV I 

XSYSTRAP (plabel ,oldplabel ) ; 



When a program begins execution, the system trap is disabled automatically. When enabled by the 
XSYSTRAP intrinsic, and subsequently activated by an error, the trap transfers control to a trap 
procedure. 

You can enable (or subsequently disable) the system trap by using the XSYSTRAP intrinsic. 

PARAMETERS 

plabel integer by value (required) 

The external -type label of the user's trap procedure. If the value of this 
entry is , the software trap is disabled . 

oldplabel integer (required) 

A word in which the previous plabel is returned to the user's program. If 
no plabel existed previously , zero is returned . 

CONDITION CODES 

CCE Request granted. Trap enabled. 

CCG Request granted. Trap disabled. 

CCL Request denied because of an illegal plabel. 

ADDITIONAL DISCUSSION 

"Enabling and Disabling Traps" in Section V. 
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INTRINSIC NUMBER 136 
Alters current Z to DB area . 

SYNTAX 



I IV 

actsize : =ZS I ZE (.size ) ; 



The ZS I ZE intrinsic alters the size of the current Z to DB area by adjusting the register offset of the 
Z address from the DB address (Z to DB). 

The Z5IZE intrinsic moves the Z address forward (expansion) or backward (contraction). If the Z to 
DB area size requested exceeds the maximum size permitted for the Z to DL (stack) area, only the 
maximum size allowed is granted. 

All changes to the Z to DB area are made in increments or decrements of 128 words, and hence the 
size actually granted may differ from the size requested. 

FUNCTIONAL RETURN 

actsize integer (optional) 

This intrinsic returns the size in words actually granted . 

PARAMETERS 

size integer by value (required) 

An integer value greater than or equal to zero that specifies the desired 
register offset (in words) for Z to DB. 

CONDITION CODES 

CCE Request granted . 

CCG The requested size exceeded the maximum limits of the Z to DL (stack) 

area. The maximum limit is granted, and this value is returned to the call- 
ing process as the value of actsize. 

CCL An illegal size parameter, less than (S - DB) + 64 words, was specified. 

This minimum value is assigned by default. 

ADDITIONAL DISCUSSION 

"Changing Stack Sizes" in Section V. 
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Some MPE functions can only be performed by users with the optional capabilities mentioned in 
Section I. This section discusses the optional capabilities needed to perform these functions. 



PRIVILEGED MODE CAPABILITY 



Users with standard MPE capabilities can only access their own code and data areas in main memory . 
A user with Privileged Mode (PM) capability, however, can access all areas of the system and can use 
all features of the hardware. They can access all system tables, and invoke all system instructions, 
including those in the privileged central processor instruction set. In short, a user with PM capability 
can use the computer on the same terms as MPE itself. MPE does not make any distinction between a 
privileged user and the operating system . 



CAUTION 



The normal checks and limitations that apply to stan- 
dard users in MPE are bypassed in Privileged Mode. It is 
possible for a Privileged Mode program to destroy file in- 
tegrity, including the MPE operating system software it- 
self. Hewlett-Packard will investigate and attempt to 
resolve problems resulting from the use of Privileged 
Mode code. This service, which is not provided under 
the standard Service Contract, is available on a time and 
materials billing basis. Hewlett-Packard will not sup- 
port, correct, or attend to any modification of the MPE 
operating system software. 

You can use Privileged Mode capability in the following ways : 

• To write permanently privileged programs that are loaded and executed entirely in Privileged 
Mode. 

• To write temporarily privileged programs that dynamically enter and leave Privileged Mode 
during execution, as required. 

Permanently Privileged Programs 

A code segment is loaded and executed directly in Privileged Mode when all the following conditions 
exist : 

1 . $ CONTROL PRIVILEGED is used or any of the segment's procedures have OPTION PRIVILEGED. 
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Optional Capabilities 



2. The program is prepared with Privileged Mode capability and resides in a group and account 
having Privileged Mode capability. You enter the appropriate capability -class attribute in the 
caplist parameter of the : PREP or : PREPRUN command that prepares the program . You must 
have Privileged Mode capability in order to enter a privileged capability class attribute and must 
be in a group and account with Privileged Mode capabilities. Refer to the MPE V Commands 
Reference Manual (32033-90006) for discussions of the : PREP and : PREPRUN commands. 

3. The NOPR IV optional parameter is omitted from the : PREPRUN or :RUN command that executes 
the program , or the CREATE intrinsic that creates a process to run it . This omission leaves the 
Privileged Mode bit ON in the appropriate CST entries . 

When you add a segment to a Segmented Library (through the -ADDSL Segmenter command), the 
procedures within the segment are checked to determine whether any of them are privileged . If they 
are, the segment is always run in Privileged Mode. In order to add a segment containing one or more 
privileged procedures to a library, you must possess Privileged Mode capability in your group and ac- 
count. Refer to the MPE Segmenter Reference Manual (30000-90011) for instructions concerning 
Segmented Libraries. 

Temporarily Privileged Programs 

Temporarily privileged programs are initiated, upon request, in the non-Privileged Mode. Then, in- 
trinsics can be used to change the program to and from Privileged Mode dynamically. For example, 
just before a set of privileged instructions is encountered, the program can be switched to Privileged 
Mode to allow execution of these instructions. Then, after the last privileged instruction in the set is 
encountered, the program can be returned to non- Privileged Mode. This bracketing of privileged in- 
structions aids in reducing system violations, since the program cannot access locations or resources 
outside the user environment when it is running in non -Privileged Mode. 

Before running a temporarily privileged program, you should understand how the central processor 
handles procedure calls (PCAL instructions) and exits (EXIT instructions) when encountered in either 
mode: 

• In Privileged Mode, when a PCAL instruction is executed, Privileged Mode is retained even 
though the destination code segment may have a nonprivileged CST entry. When an EXIT in- 
struction is encountered, the resulting mode depends on the status word in the stack marker. 

• In non -Privileged Mode, when a PCAL instruction is encountered, the mode is obtained from the 
CST entry for the destination code segment. When an EXIT instruction occurs, the resulting 
mode is taken from bit (0:1) of the status in the stack marker. If the entry indicates Privileged 
Mode, ((0: 1 )»1) a system violation occurs. 

In general , the status word determines the action taken in Privileged Mode , but the CST determines 
the action in non -Privileged Mode. Refer to the Machine Instruction Set Reference Manual 
(30000-90022) for further discussions of the PCAL and EXIT instructions. 

A code segment is loaded and begins execution as a temporarily privileged segment (in non -Privileged 
Mode) when three conditions are met: 
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Optional Capabilities 

1. The program is prepared with Privileged Mode capability, by entering the appropriate 
capability-class attribute in the caplist parameter of the :PREP or rPREPRUN command. This 
requires that you have Privileged Mode capability as a user and must be in a group and account 
with Privileged Mode capabilities . 

2. $CDNTR0L PRIVILEGED was not used. 

3. None of the segment's procedures have OPTION PRIVILEGED. 

The NOPRIV parameter of the :PREPRUN and :RUN commands forces all segments in the program to 
begin execution in user mode. When a temporarily privileged segment is loaded, the CST entry cor- 
responding to that segment has its Privileged Mode bit (1 : 1 )=0. 

If you possess Privileged Mode capability, you can also call all intrinsics available to users with the 
Data Segment Management capability (DS) , provided that you follow these rules : 

• When calling the data segment intrinsics from Privileged Mode , ensure that the DB register points 
to its normal stack position. When the GETDSEG intrinsic is used to create extra data segments 
under these conditions, the number of segments that can be created is dependent on the space 
available in the Process Control Block Extension (PCBX) and cannot be calculated. 

• When a temporarily privileged process calls a data segment intrinsic while in non -Privileged 
Mode, the data segment index returned to the calling process can also be used by the process to 
reference that segment in Privileged Mode. If the process calls a data segment intrinsic in 
Privileged Mode, however, the returned index cannot be used to reference the segment in non- 
Privileged Mode . 

Entering Privileged Mode 

The GETPR I VMODE intrinsic is used to switch a temporarily privileged program from non-Privileged 
Mode to Privileged Mode. This intrinsic turns on the Privileged Mode bit in the status register 
((0:1)-1), but leaves the Privileged Mode bit in the Code Segment Table (CST) entry for the execut- 
ing segment ((1 :1)=0). Thus, if additional segments are run as part of the program, they will run in 
Privileged Mode unless GETUSERMODE is specifically called to return to the non -Privileged Mode, since 
the status register not the CST determines a mode change when in Privileged Mode. 

Figure 3-1 contains a program that uses the GETPR I VMODE intrinsic to switch to Privileged Mode. 
Privileged Mode is necessary temporarily because the program opens a file with both NOBUF and 
NOW AIT aoptions specified in the FOPEN intrinsic call. Privileged Mode capability (PM) is required 
to call this intrinsic, however, caution should be used since your I/O could overwrite other data on 
the system. 

The program in Figure 3-1 was prepared with the CAP=PM parameter specified in the :PREP com- 
mand. This enables the program to be switched from non-Privileged to Privileged Mode with the 
GETPR I VMODE intrinsic. Statement 00019000 in the program switches the program from non- 
Privileged to Privileged Mode before the next statement opens a file with both the NOBUF and 
NOW AIT aoptions specified . 

The statement CCGC2); in line 00019000 causes the program to quit if CCG (signifying that the 
program already is running in Privileged Mode) is returned. 
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Optional Capabilities 
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OA.08.01 [4W] (C) HEWLETT-PACKARD COMPANY 1980 

SCONTROL USLINIT 

BEGIN 

BYTE ARRAY 0UTPUT(0 : 16 ) : -"OUTPUT " ; 
BYTE ARRAY TNAM(0 : 6 ) : = "DA TAIN "; 
BYTE ARRAY DEV(0 : 7) : ="LP TERM "; 

INTEGER OUT, FILE, LGTH , I : =1, PROMPT : ="? " ,DONE:=0; 
EQUATE MAXTRM=3; 
ARRAY BUFR(0:36*MAXTRM) ; 
INTEGER ARRAY OPEN(0 :MAXTRM) ; 
DEFINE CCL = IF < THEN QUIT#, 
CCG = IF > THEN QUIT#, 
CCNE= IF <> THEN QUIT#; 
INTRINSIC FOPEN,FREAD,FWRITE,FCLOSE,GETPRIVMODE,GETUSERMODE, 

IOWAIT.QUIT; 
<<END OF DECLARATIONS^ 

0UT:=F0PEN(0UTPUT,4,1, ,DEV) ; CCL(l); <<LINEPRTR 0UTPT>> 
WHILE (I:=I+1)<MAXTRM DO <<LOOP-SET UP TRMS>> 

BEGIN 

GETPRIVMODE; CCG(2); << NOWAIT FOPEN>> 

FILE:=FOPEN(TNAM,%405,%4404,36,DEV(3));<<INPUT TERM>> 



CCL{3) ; 

GETUSERMODE; CCG(4); 
OPEN(I):«FILE; 
FWRITE(FILE, PROMPT, 1, %320) ; 
IOWAIT(FILE); CCNE(6); 
FREAD( FILE, BUFR( 1*36), -72) ; 
END; 



<<CHECK FOR ERR>> 
<<N0WAIT I/0>> 
<<SAVE FILE NMBRS>> 

CCNE(5);<<OUTPUT PRMPT>> 
<<C0MPLETE REQST>> 

CCNE(7) ;<<INPT DATA>> 



WAIT: 



<<WAIT FOR 1ST DNE>> 
<<E0F ON TERM READ>> 



<<TERMINAL FILE>> 



FILE:=I0WAIT(0, ,LGTH) ; CCL(8); 
IF > THEN 
BEGIN 

FCLOSE(FILE,0,0); CCL(9); 
IF(DONE:=DONE+l)>=MAXTRM THEN GO EXIT;<<TERMS CLSD?>> 
END 
ELSE 
BEGIN 

I:=-l; <<SET BUFFER INDEX>> 

DO I: =1+1 <<INCR BUFR INDX>> 

UNTIL OPEN(I)=FILE OR I=MAXTRM; <<SRCH FOR FILE NO>> 



IF I=MAXTRM THEN QUIT(IO); 
FWRITE(0UT,BUFR(I*36) ,-LGTH 
CCNE(ll); 

FWRITE(FILE, PROMPT, 1,%320) ; 
IOWAIT(FILE); CCNE(13); 
FREAD( FILE, BUFR (1*36) ,-72); 
END; 
GO TO WAIT; 
EXIT:END. 



<<FILE NOT FOUND>> 
,0) ; <<COPY INPUT TO LP>> 

<<CHECK FOR ERR>> 
CCNE(12) ;<<0UTPT PRMPT>> 

<<COMPLETE REQUEST) > 
CCNE(14) ; <<INPT DATA>> 

<<C0NTINUE>> 



Figure 3- 1 . Using the GETPRIVMODE and GETUSERMODE Intrinsics (Program DSINIT) 
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Optional Capabilities 

Entering Non-Privileged Mode 

The GETUSERMODE intrinsic is used to change a temporarily privileged program from Privileged to 
non -Privileged Mode, by changing the Privileged Mode bit in the status register to OFF ((0: 1 )=0). 

The intrinsic call GETUSERMODE;, is illustrated in line 00022000 of Figure 3-1. 

Moving the DB Pointer 

If you have the Data Segment Management capability (DS) and run a process with an extra data seg- 
ment in Privileged Mode , you can prepare for movement of data between this segment and the stack 
with the SW I TCHDB intrinsic. This intrinsic changes the DB register so that it points to the base of the 
extra data segment rather than the base of the stack. The SW I TCHDB intrinsic returns the logical in- 
dex of the data segment indicated by the previous DB register setting, allowing you to restore this set- 
ting later. If the previous DB setting indicated the stack, zero is returned. 

For example, to set the DB register so that it points to the base of an extra data segment whose logical 
index is indicated in the word INDEX 2, enter the following intrinsic call: 

SET:=SWITCHDBCINDEX2): 

INDEX2 is a logical value denoting the logical index of the data segment to which the DB register is 
switched, as obtained through the GETDSEG intrinsic call. MPE checks the value specified for this pa- 
rameter to insure that the process has previously acquired access to this segment. For an extra data 
segment, this parameter must be a positive, nonzero integer. To switch back to the stack, this pa- 
rameter must be zero. 

Since a user-mode call to GETDSEG generates a value for index of the assigned entry or an error code 
of %2000-%2004, a Privileged Mode call to GETDSEG must be made to ensure that the value for index 
is the actual segment entry number for the data that was assigned. The calling process is aborted if 
the SW I TCHDB intrinsic is called from a program which is not running in Privileged Mode. 

Scheduling Processes 

Every process in the system is assigned a priority. When a process is ready to run, it is placed in the 
READY list. When the dispatcher runs, it selects the process in memory with the highest priority for 
execution . 

The Master Queue (see Figure 3-2) is divided into logical areas, each corresponding to a particular 
type of dispatching and priority class for the processes within it. A logical area can be a linear sub- 
queue, a circular subqueue, or a portion of the main Master Queue. In a linear subqueue, the process 
with highest priority accesses the central processor first and maintains this access until the process 
either is completed, terminated, or suspended to await the availability of a required resource. In a 
circular subqueue, all processes access the central processor for an interval (time quantum) of maxi- 
mum duration (or until completed, terminated, or suspended). At the end of this duration, control is 
transferred to another process in the queue if no process with a higher priority is ready to be dis- 
patched. This time allocation is controlled by the system timer. Processes that are not scheduled in a 
subqueue are scheduled in the Master Queue. 
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Optional Capabilities 

Each linear subqueue in the Master Queue is defined by a single priority number, and each circular 
subqueue is defined by a range of priority numbers. While the standard user is aware of the priority 
class associated with a subqueue, only a user with System Supervisor (OP) or Privileged Mode (PM) 
capability can manage priority numbers. The standard subqueues (priority classes) are as follows: 

A5 A linear subqueue containing processes of very high priority. Its priority 

range is 30-99 , and it is presently used only by MPE. 

Scheduling Type : Linear 

Priority Range: 30 (+ rank to a maximum of 99) 

BS A linear subqueue containing processes of high priority. It is accessible to 

users having MAXPRI=BS. Normally, priority for a BS process is 100. 
However, by specifying a rank >0 in the GETPRIORITY intrinsic, the 
process may be set in the Master Queue at min value of (100 + rank, 1 49) . 

Scheduling Type : Linear 

Priority Range : 1 00 (+ rank to a maximum of 149) 

cs A circular subqueue generally devoted to interactive sessions. A CS process 

whose CPU time between priority changes exceeds the "average short trans- 
action" time will be lowered in priority, but not below the C Subqueue 
Priority Limit, called CLIMIT, which may be set by the :TUNE command. 
Refer to the MPE V Commands Reference Manual (32033-90006) for 
more information on the :TUNE command. 

Scheduling Type : Circular 
Priority Range : CB ASE -CLIMIT 

D S A circular subqueue generally devoted to batch jobs. A DS process whose 

CPU time between priority changes exceeds the background quantum will 
be lowered in priority, but not below the D Subqueue Priority Limit, or 
DLIMIT, which may be set by the :TUNE command. Refer to the MPE V 
Commands Reference Manual (32033-90006) for more information on the 
: TUNE command. 

Scheduling Type: Circular 
Priority Range : DBASE -DLIMIT 

ES A circular subqueue generally used for background processes. An ES 

process whose CPU time between priority changes exceeds the background 
quantum, will be lowered in priority, but not below ELIMIT. Such a 
process will have a minimal impact on the performance of processes in 
other subqueues. 

Scheduling Type: Circular 
Priority Range: EBASE-ELIMIT 
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LINEAR 
QUEUES 



DBASE 



DUMIT 



NOTE: Parameters are 
modifiable by :TUNE 
command only. 



150 < 



PRIORITY 
NUMBER 

V 




255 



C BASE, C LIMIT 
D BASE, D LIMIT 
E BASE, E LIMIT 



< 255 



HIGH PRIORITY 



CBASE 



CLIMIT 



EBASE 



EUMIT 

LOW PRIORITY 



Figure 3-2. Master Queue Structure 
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In all cases , it should be remembered that low numeric values mean high priority in the system . 

The System Manager/System Supervisor (only users with OP capability) has the ability to modify the 
values of the starting priority (BASE) and priority limits (LIMIT) for each circular queue, as well as 
the average short transaction limit and background quantum, via the : TUNE command. 

A CS process is given a priority of CBASE when it begins (see Figure 3-2). When a process stops (e.g. 
for disc I/O, terminal I/O, pre-emption), its new priority is determined so that it may be requeued 
for the CPU. If the process has completed a transaction, (a transaction is defined as the time between 
terminal reads), the priority becomes CBASE. The value of an "average short transaction" is then 
recalculated. If the CS process has not completed a transaction, and if the process has exceeded the 
average short transaction filter value since its priority was last reduced , the priority is decreased , but 
will not be lower than CLIMIT. 

DS and ES processes begin at DBASE and EBASE respectively , and are rescheduled according to the 
same criteria used for CS processes. The exception is that a fixed value (the value of max which has 
been specified for the DS subqueue) is used for the DS and ES subqueues in place of the average short 
transaction value, which is used for CS processes only. 

The priority class of a process can be specified by the user with PH capability. In the two-character 
string that comprises a priority class reference , the first character refers to the location of a subqueue 
within the Master Queue (in alphabetical order) and the second character specifies whether the logical 
area is the subqueue itself (S) , or the portion of the Master Queue (M) that immediately follows the 
subqueue. When a priority class is requested for a process, it is assigned the highest priority within 
that class (relative to other processes already assigned the same class). In a circular subqueue, the ac- 
tual priority of the process is modified as other processes use central processor time. 

Only a user with Privileged Mode capability can assign a priority number to a process. Priority num- 
bers range from 1 to 255 inclusively , with 1 denoting the highest priority . Any two processes having 
the same priority number are in the same subqueue . 

Priorities are assigned to processes through the priorityclass parameter of the CREATE and/or 
GETPRIDRITY intrinsic. Because users with the Privileged Mode (PM) capability can schedule 
processes within the Master Queue , the priorityclass parameter can take on the following values : 

• A string of two ASCII characters describing the standard priority class (subqueue) in which the 
process is to be scheduled: AS, BS, CS, D5, or ES. 

• An ASCII character or characters (x) specifying a valid subqueue, followed immediately by the 
single -character string M, indicating the Master Queue, or S, indicating the subqueue. 

The word format is : 
BITS 




This schedules the process in that region of the Master Queue directly adjacent to and below the 
subqueue x. The process is scheduled in the first available priority in that region. 
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An ASCII character or characters (y) specifying an absolute priority number, followed by the 
single-character string A indicating that y is an absolute priority number. The word format is: 



BITS 




This schedules the process at the location specified by y in the Master Queue. If another process or 
subqueue already occupies the location designated by y, the process is placed in the first location 
available moving toward the ES subqueue , and the process priority number is changed to reflect 
that location. 



DATA SEGMENT MANAGEMENT CAPABILITY 



During execution of a user program, many processes may be created, run, and deleted. For each 
process in execution, one or more "code segments" and one "data segment" exist. The data segment is 
private to the process and contains the data generated and manipulated by that process. In a user 
process, this segment is referred to as the "user's stack segment". (Refer to the HP 3000 Computer 
Systems General Information Manual (5953-7553) for further discussion of segments, processes, and 
the stack . ) 

A particular program, which consists of code segments, can be run by many user processes simul- 
taneously, with all user processes accessing the same body of code. The stack segment, however, is 
private to each user process and cannot be shared among others. User processes created by a user with 
the standard MPE capabilities may create and access one stack segment only. 

MPE allows users with the Data Segment Management (DS) capability, however, to create and access 
extra data segments for their processes during a job or a session. These segments are used for tem- 
porary storage of data while the creating processes exist. Each segment is assigned an identity that 
either allows it to be shared between different processes in a job or session , or declares it as private to 
the creating process. All private data segments created by a process are either deleted explicitly with 
the FREEDSEG intrinsic or are destroyed automatically when the process terminates. Sharable data 
segments are saved until explicitly deleted by the last process which is sharing them, or until that 
process terminates, at which time they are destroyed. 

Extra data segments are not directly addressable by user processes. They can be accessed only through 
intrinsics (DMOVIN, DM0V0UT) that move data between the user's stack and the extra data segments. 
If a program (or process running a program) without Data Segment Management capability attempts 
to call these intrinsics, that process is aborted. The Data Segment Management capability is assigned 
to the program at : PREP time by a user with this capability ( :PREP. .. ;CAP=DS). 

The maximum number of extra data segments allowed per process and the maximum size of each seg- 
ment is determined at system configuration time. 
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A user who possesses the Data Segment Management capability , can : 

• Create an extra data segment. 

• Transfer data from an extra data segment to the stack. 

• Transfer data from the stack to an extra data segment. 

• Change the size of an extra data segment. 

• Delete an extra data segment. 

Creating an Extra Data Segment 

A process can create or acquire an extra data segment with the GETDSEG intrinsic . The number of ex- 
tra data segments that can be requested, and the maximum size of these segments, are limited by 
parameters specified when the system is configured. When an extra data segment is created, the 
GETDSEG intrinsic returns a logical index number, assigned by MPE, to the calling process that allows 
this process to reference the segment in later intrinsic calls . 

The GETDSEG intrinsic is also used to assign the segment an identity that either allows other processes 
in the same job or session to share the segment, or declares it private to the calling process. If the 
segment is sharable, other processes in the same job/session can obtain its logical index (through 
GETDSEG) and use this index to reference the segment. Thus, the logical index is a local name that 
identifies the segment throughout any process that obtained the index with the GETDSEG intrinsic 
call. The logical index need not be the same value in all processes sharing the segment. The GETDSEG 
intrinsic may return different logical index numbers to different processes , even though each process 
referenced the same data segment in their intrinsic calls. The identity, on the other hand, is a job- 
or session -wide name that allows any process to identify the data segment in order to obtain a logical 
index . 

Figure 3-3, 3-4, and 3-5 each contain a program which illustrates the use of the GETDSEG, 
DMQVOUT, or DMDV IN intrinsic. Together, these three programs do the following: 

1 . Create an extra data segment which can be shared by all three processes. 

2. Compute Julian calendar dates (a Julian date is the sequential number of the day within the 
year; e.g. February 1 is represented as "32"). 

3. Transfer the Julian calendar dates from the array to the extra data segment. 

4. Create and activate two processes of the program shown in Figure 3-5, each of which shares the 
same code , but has its own data stack . 

5 . Each of the processes created in Step 4 above : 

a. Opens a terminal for input/output, and once a :DATA filename command is entered on 
the terminal, requests month and day information from the user. 

b . Moves the Julian dates , for the month entered by the user , from the extra data segment to 
its own stack. 
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c. Computes the Julian date, based on the day of the month entered by the user, and displays 
this information on the terminal. 

The program in Figure 3-3, called DSINIT, creates an extra data segment 372 words long, fills an ar- 
ray with values representing Julian calendar dates for a particular year entered by a user, then trans- 
fers this information from its stack to the extra data segment . 

The program in Figure 3-4, called DSBOSS, creates and activates two processes. Each of the two 
processes created is a process to run the program shown in Figure 3-5. Thus, each process shares the 
same code, but has its own data stack. The program in Figure 3-5 called DSACCS, opens a terminal 
for input/output, acquires the extra data segment created by DSINIT, requests a month and day from 
the user, then transfers the Julian dates contained in that particular month into its own data stack. 
Because DSBOSS (Figure 3-4) has created two processes for the program shown in Figure 3-5, and 
has activated both processes, the functions performed by DSACCS are duplicated (i.e. two terminals 
are opened for input/output, or two users can enter the month and day). 



NOTE 



The three programs in Figures 3-3, 3-4, and 3-5 must 
specify the Data Segment (DS) or Process Handling (PH) 
capability when they are prepared, as follows: 

DSINIT (Figure 3-3): 

:PREP $OLDPASS,DSINIT;CAP=DS, IA,BA 
DSBOSS (Figure 3-4): 

:PREP $0LDPASS, DSBOSS ;CAP=PH, IA,BA 
DSACCS (Figure 3-5): 

:PREP $OLDPASS,DSACCS;CAP=DS,IA,BA 

In all cases above , it is assumed that I0LDPASS contains 
the compiled USL file for each of the three programs. 

In Figure 3-3, the statement (0001 1000/00012000) initializes a 12- word integer array to represent 
the number of days in each month of the year: 

INTEGER ARRAY MAXDAYC0:11 ): =31 ,28,31 ,30,31 ,30 

31,31,30,31,30,31; 

The next statement (0001 3000) of program DSINIT declares a 3 7 2- word integer array and initializes 
all 372 words to -1 : 

INTEGER ARRAY CALENDARC0:371 ):=372(-1 >; 

The two F0PEN intrinsic calls open $STDINand $STDLISTso that FREADand FWR I TE intrinsic calls 
can be issued against these files. 
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PAGE 0001 HEWLETT-PACKARD 32100A.08.1 
00001000 00000 SC0NTR0L USLINIT 
BEGIN 



SPL[4W] TUE, OCT 28, 1982, 4:35 PM 



00002000 00000 
00003000 00000 1 
00004000 00004 1 
00005000 00005 1 
00006000 00005 1 
00007000 00005 1 
00008000 00017 1 
00009000 00001 1 
00010000 00001 1 
00011000 00006 1 
00012000 00006 1 
00013000 00014 1 
00014000 00001 1 
00015000 00001 1 
00016000 00001 1 
00017000 00001 1 
00018000 00001 1 
00019000 00001 1 
00020000 00001 1 
00021000 00001 1 
00022000 00012 1 
00023000 00025 1 
00024000 00025 1 
00025000 00035 1 
00026000 00035 1 
00027000 00044 1 
00028000 00044 1 
00029000 00054 1 
00030000 00065 1 
00031000 00075 1 
00032000 00075 1 
00033000 00105 1 
00034000 00105 1 
00035000 00112 1 
00036000 00127 1 
00037000 00132 2 
00038000 00140 2 
00039000 00141 2 
00040000 00143 1 
00041000 00143 1 
00042000 00150 1 
00043000 00153 1 END. 

PRIMARY DB STORAGE=%021 ; 

NO. ERRORS=000; 

PROCESSOR TIME=0:00:03; 



BYTE ARRAY INPUT (0 : 5 ) : =" INPUT "; 
BYTE ARRAY OUTPUT (0 : 6 ): ="0UTPUT "; 

INTEGER IN , OUT , LGTH .MONTH .DAY , YEAR .DATE : =1 .DSLGTH : =372 ; 
LOGICAL DSINDX; 

ARRAY READ(0:14):="GENERATE CALENDAR DATA SEGMENT"; 
ARRAY BUFR(0:1) :=2(" "); 
BYTE ARRAY BBUF (*) =BUFR ; 
ARRAY REQST(0:5):="ENTER YEAR: "; 
INTEGER ARRAY MAXDAY(0 : 11 ) : =31 , 28 ,31 , 30 , 31 , 30 , 

31,31,30,31,30,31; 
INTEGER ARRAY CALENDAR (0 :371) : -372(-l) ; 
DEFINE CCL = IF < THEN QUIT#, 
CCNE= IF <> THEN QUIT#; 

INTRINSIC FOPEN , FREAD , FWRITE .GETDSEG .DMOVOUT , BINARY , QUIT ; 



<<END OF DECLARATIONS>> 

IN:=F0PEN(INPUT,%45); CCL(l); 
0UT:=F0PEN(0UTPUT,%414,1); CCL(2); 

FWRITE (OUT, HEAD, 15,0 ) ; CCNE(3); 

GETDSEG(DSINDX, DSLGTH, "JD" ) ; CCL(4) 

FWRITE(0UT,REQST,6,%320) ; CCNE(5) ; 
LGTH:=FREAD(IN,BUFR,-4) ; CCNE(6) ; 
YEAR :=BINARY( BBUF, LGTH) ; CCNE(7) ; 



<<$STDIN>> 
<<$STDLIST>> 

<<PR0GRAM ID>> 

;<<SHARED EXTRA DS>> 

<<REQST CLNDR YR>> 
<<INPUT YEAR>> 
<<CONVERT YEAR>> 



IF YEAR MOD 4=0 THEN MAXDAY( 1 ) : =29 ; <<FIX FEB-LEAP YR>> 

FOR MONTH: =0 UNTIL 11 DO <<INDEX 12 MONTHS>> 

FOR DAY:=0 UNTIL MAXDAY( MONTH )-l DO<<INDEX DAYS/EA M0>> 
BEGIN 

CALENDAR (M0NTH*31+DAY ) : =DATE ; 
DATE:=DATE+1 
END; 



<<SET JULIAN DATE>> 
<<INCR JULIAN DATE>> 



DMOVOUT (DSINDX, 0,372, CALENDAR) ; 
CCNE(8); 

SECONDARY DB ST0RAGE=%00636 
NO. WARNINGS=000 
ELAPSED TIME=0:00:10 



<<JULIAN CLNDR TO DS>> 
<<CHECK FOR ERROR>> 



Figure 3-3. Using the GETDSEG and DMOVOUT Intrinsics (Program DSINIT) 
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SCONTROL USLINIT 


00002000 


00000 





BEGIN 


00003000 


00000 


1 


BYTE ARRAY INPUT(0 :5) : ="INPUT "; 


00004000 


00004 


1 


BYTE ARRAY OUTPUT(0 :6 ) : ="0UTPUT " ; 


00005000 
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1 


INTEGER IN,0UT,LGTH,PIN1,PIN2; 


00006000 
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1 


BYTE ARRAY PFILE (0 :6 ) : =DSACCS "; 


00007000 
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1 


ARRAY MESSAGE(0:29):="WHEN ALL JULIAN DATE OPERATIONS ARE 


00008000 


00022 


1 


"COMPLETE TYPE: DONE . " ,%6412 , "? "; 


00009000 


00036 


1 


ARRAY BUFR(0:1); 
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1 


BYTE ARRAY BBUF (*) =BUFR ; 
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DEFINE CCL= IF < THEN QUIT*, 


00012000 
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CCNE= IF <> THEN QUIT#; 
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00014000 
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INTRINSIC FOPEN.FWRITE.FREAD, CREATE, ACTIVATE, QUIT; 
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<<END OF DECLARATIONS>> 


00017000 
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00018000 
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IN:=FOPEN(INPUT,%45); CCL(l); <<$STDIN>> 
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OUT:=FOPEN(OUTPUT,%414,1); CCL(2); <<$STDLIST>> 
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CREATE(PFILE, .PIN1.1) ; CCNE(3); <<S0N 1-TERMID1 FILE>> 
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1 


CREATE(PFILE, .PIN2.2) ; CCNE{4); <<S0N 2-TERMID2 FILE>> 
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1 
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ACTIVATE (PIN1.0) ; CCNE(5); <<S0N 1>> 
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ACTIVATE (PIN2.0 ) ; CCNE(6); <<S0N 2>> 
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WAIT: 
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FWRITE(OUT, MESSAGE, 30, 5S320) ; CCNE (7 ) ; <<TERMNATN INSTR>> 


00029000 
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LGTH:=FREAD(IN,BUFR,-4) ; CCNE(8); <<SUSPD FOR READ>> 
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1 


IF BBUF<>"D0NE" THEN GO WAIT; <<END IF DONE-KILLS S0NS>> 


00032000 
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1 


END. 


PRIMARY 


DB STORAGE =%013; SECONDARY DB STORAGE=%00053 


NO. ERRORS=000; 


NO. WARNINGS=000 


PROCESSOR TIME=( 


1:00:02; ELAPSED TIME =0 : 00 : 09 



Figure 3-4. Creating and Activating Two Son Processes (Program DSBOSS) 
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<<FORMALDES #=1 OR 2>> 
<<TERM FILE TERMI0# >> 
<<CHECK FOR ERR0R>> 
<< PROGRAM ID>> 
<<SHARED CALENDAR DS>> 
<<ERR OR NONEXISTENT>> 



TT-PACKARD 32100A.08.1 SPL[4W] TUE , OCT 28, 1982, 4:35 PM 
SCONTROL USLINIT 
BEGIN 
BYTE ARRAY NAME ( : 7 ) : ="TERMIO# " ; 
BYTE ARRAY DEV(0 :4) : ="TERM "; 

INTEGER FNO , LGTH .MONTH , DAY .DSLGTH , JDATE , CURRENT : =1 ; 
LOGICAL DSINDX,PARM=Q-4; 
ARRAY READ(0:9) :="JULIAN DATE CALENDAR"; 
ARRAY BUFR(0:1) ; 
BYTE ARRAY BBUFR (*) =BUFR ; 

ARRAY MESSAGE (0 : 16 ):="MONTH = " , "DAY = "."JULIAN DATE = " ; 
BYTE ARRAY BMSG(*) =MESSAGE ; 
ARRAY DATES(0:30) ; 
DEFINE CCNE = IF <> THEN QUIT#; 

INTRINSIC FOPEN , FREAD , FWRITE , GETDSEG , DMOVIN , BINARY , ASCII ,QUIT ; 
<<END OF DECLARATIONS>> 
NAME(6) :=PARM; 

FNO : =FOPEN( NAME ,%405 ,4,36 ,DEV) 
IF < THEN QUIT(l) ; 
FWRITE(FNO, READ, 10,0); CCNE(2) 
GETDSEG(DSINDX,DSLGTH,"JD") ; 
IF <= THEN QUITO); 
GETMO: 

FWRITE (FNO, MESSAGE, 4, %320); CCNE (4) ; <<REQUEST MONTH>> 
MOVE BUFR:=" " ; <<BLANK READ BUFFER>> 

LGTH:=FREAD(FN0,BUFR,-2); CCNE (5 ) ; < <INPUT M0NTH>> 
IF LGTH=0 THEN GO EXIT; 
MONTH: =BINARY(BBUFR, LGTH) ; 
IF <> THEN GO GETMO; 

IF NOT(K=M0NTH< = 12) THEN GO GETMO; < <ILLEGAL MONTH CHK>> 
GETDA: 

FWRITE(FN0,MESSAGE(4),3,%320); CCNE(6) ; <<REQUEST DAY>> 
MOVE BUFR:=" "; <<BLANK READ BUFFER>> 

LGTH:=FREAD(FN0,BUFR,-2); CCNE (7 ) ; <<INPUT DAY>> 
DAY:=BINARY(BBUFR,LGTH) ; 
IF <> THEN GO GETDA; 
IF N0T(K=DAY<=31 THEN GO GETDA; 
IF MONTHOCURRENT THEN 
BEGIN 

DM0VIN(DSINDX,(M0NTH-1)*31,31,<<GET MO FRM CLNDR>> 

DATES); CCNE (8); <<CHECK FOR ERR0R>> 
CURRENT :=M0NTH; <<UPDATE MONTH IN BUFR>> 

END; 
JDATE : =DATES(DAY-1 ) ; <<GET JULIAN DATE>> 

IF JDATE<0 THEN GO GETDA; ^UNINITIALIZED DATE>> 

MOVE MESSAGE (14) :=" " ; <<BLANK OUTPUT BUFR>> 

LGTH:=ASCII(JDATE,10,BMSG(28)) ; <<CNVRT JULIAN DATE>> 
FWRITE(FN0,MESSAGE(7),10,0) ; CCNE (9 ) ; <<OUTPT DATE-TERM#>> 
GO GETMO; <<CONTINUE>> 

EXIT:END. 



<<NO MONTH - DONE>> 
<<CONVERT MONTH>> 
<<IF BAD TRY AGAIN>> 



<<CONVERT DAY>> 
<<IF BAD TRY AGAIN>> 
<<ILLEGAL DAY CHK>> 
<<MONTH NOT IN BUFR>> 



Figure 3-5. Using the GETDSEG and DMOVIN Intrinsics (Program DSACCS) 
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An extra data segment is created with statement 00026000 in Figure 3-3: 

GETDSEGCDSINDX ,DSLGTH, "JD") ; 

The parameters specified are : 

index The logical word DSINDX, to which the logical index number of the data 

segment will be returned. This index is used to refer to this data segment 
in later intrinsic calls from this process. 

length DSLGTH, which has been initialized to 372 words (see statement 00005000 

in Figure 3-3). 

id "JD", which specifies that this data segment is sharable by other processes 

in the same job/session. Any process which is to create or share an extra 
data segment must have the Data Segment (DS) capability. If the data 
segment being created is private to the creating process, specify for id. 

Statements 00028000, 00029000, and 00030000 in Figure 3-3 request the user to enter the calen- 
dar year, and convert this ASCII string to a binary value. 

Statement 00032000 of Figure 3-3 checks if the year is equally divisible by four, and if it is, adds 
the twenty -ninth day to February for the leap year. 

The six statements beginning on line 00034000 of Figure 3-3 establish two FOR loops. The inner loop 
steps from to the maximum number of days minus 1 for each entry in the array MAXDAY. For ex- 
ample, when MONTH = 0, MAXDAYCMDNTH) = 31, thus the FOR loop performs 31 iterations (0 to 
MAXDAYCM0NTH)-1). 

Statement 00038000 of Figure 3-3 increments the date each time the FOR loop is repeated. When 
the inner loop is satisfied, the MONTH FOR loop steps one iteration and the inner loop repeats. The ar- 
ray CALENDAR is filled with Julian dates. All elements of the array were initialized to -1, and posi- 
tions in the array that retain the value -1 signify invalid dates. 

The data contained in CALENDAR is transferred from the stack to the extra data segment with state- 
ment 00041000 of Figure 3-3: 

DM0V0UT CDS I NDX, 0,372, CALENDAR) 

The parameters specified are : 

index DSINDX, which contains the logical index returned by MPE when the 

GETDSEG intrinsic was executed. 

disp 0, which specifies the first word in the data segment. This is the starting 

location for the first word transferred from CALENDAR to the extra data 
segment . 

number 372, which specifies the size, in words, of the data block to be transferred. 

location CALENDAR, which specifies the starting address in the stack, of the data 

block to be transferred. 
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At this point , the following events have occurred : 



:RUN DSINIT 



± 



EXTRA DATA 

SEGMENT 

ENTERED 



<r 



> 



CALENDAR YEAR 
1976 ENTERED 



± 



ARRAY CALENDAR 
FILLED WITH 
JULIAN DATES 



y. 



DATA IN CALENDAR 
TRANSFERRED TO 
EXTRA DATA SEGMENT 



When the :RUN DSBOSS command is entered, the program in Figure 3-4 (DSBOSS) executes. 

Statements 00018000 and 00019000 of Figure 3-4 open $STDINand $STDLISTto accept FREADand 
FWR I TE intrinsic calls . 

Statement 00021000 of Figure 3-4: 

CREATECPFILE,,PIN1,1)j 

creates a process. The parameters specified are: 

ppogname PFILE, a byte array containing the string "DSACCS" which is the name of 

the file containing the program to be run. Note that DSACCS is the name 
of the program in Figure 3-5, thus the process is created for this program. 



entryname 



pvn 



param 



Omitted; a comma place holder is used. The primary entry point is 
specified by default. 

PIN1, a word to which the Process Identification Number of the process 
will be returned . 

1 , a parameter used to transfer control information to the new process. 
The new process can access this control information (1) in location Q-4 of 
its data stack . 



All other parameters are omitted from the CREATE intrinsic call . 

Statement 00022000 of Figure 3-4 also creates a process for the program DSACCS. This time the 
Process Identification Number is returned to PIN2, and the control parameter 2 is located at stack 
location Q-4 for this process. 
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The two ACTIVATE intrinsic calls activate the two processes; the susp parameter specifies that the 
father process will not be suspended when the sons are activated. Program DSBOSS, therefore, has 
created and activated two processes as follows : 




The four statements beginning with 00027000 of Figure 3-4 suspend DSBOSS for I/O until "DONE" is 
entered on $STDIN. DSBOSS did not suspend when the sons were activated. The reason for this is 
that when two or more sons are created , and the father is suspended when the last son is activated , it 
is possible that the sequence of events will be such that the sons are unable to reactivate the father. 
The following sequence illustrates how this could happen : 

1 . Create two sons. Activate SON1 . 
Father and SON1 both active. 

2. Activate SON 2. Suspend father. Father expects to be reactivated when either son terminates . 
Father suspended; SON1 and SON 2 active. 

3. SON1 terminates, reactivating father. Father reactivates, determines that SON 2 is still active, 
and resuspends itself. However, while the father was active, SON2 terminated. The attempt 
by SON 2 to reactivate the father failed, because the father was already active. Thus, when the 
father resuspends itself, it suspends indefinitely because both sons have terminated. 

The two processes, SON1 and SON 2, both of which are DSACCS, are shown in Figure 3-5. 
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Statement 00017000 of Figure 3-5: 

FNO:=FOPENCNAME,%405,4,36,DEV); 

opens a terminal for input/output . The parameters specified are : 

formaldesignator NAME, which contains the string TERMI01 when this call is issued by SON1 

and TERM 1 02 when the call is issued by SON 2. Note that in statement 
00003000 of Figure 3-5, NAME is set equal to TERMID#. The statement: 

NAMEC6):=PARM: 

however, replaces "#" with 1 or 2, depending on the parameter contained 
in stack location Q-4. (This parameter was passed to the process by the 
CREATE intrinsic call in program DSBOSS.) Thus, by using different for- 
mal designators, SON1 opens one terminal, and SON 2 opens another. 



foptions 



aopt-Lons 

reosize 

device 



NOTE 



Unlike disc files, where each formal designator must be 
unique in its domain (temporary or permanent), two or 
more devices can be opened with the same formal desig- 
nator . For example , the two : DATA commands : 

:DATA FIELD. SUPPORT; TERM 10 
:DATA FIELD. SUPPORT ;TERMI0 

would cause MPE to search the device directory for two 
available terminals and, if two are available, both 
would be allocated. Using different formal designators, 
however, allows a user to direct output to a particular , 
terminal with a : FILE command. 

%405, which specifies the following: 

(H:2)=01 The file is an old file. 

(13 : 1 )=1 Type ASCII. 

(10:3)=000 Actual file designator is the same as the formal file designator. 

(8:2)=00 Fixed-length records. 

(7: 1)=1 Carriage -control character expected. 

4, which specifies input/output access. 

36, specifying 36 words. 

DEV, a byte array specifying the device class ( " TERM " ) . 



All other parameters are omitted from the FOPEN intrinsic call . 



3-18 



Optional Capabilities 

The shared data segment is acquired with the statement : 

GETDSEG CDS I NDX , DSLGTH , ' ' JD" ) ; 

Note that the process quits unless CCG, signifying that an extra data segment with this identifier ex- 
ists already, is returned. (See Figure 3-5, Statement 00025000.) 

A month is requested from the user and the input is converted to binary. The user then is requested 
to enter a day, and this information is read and converted to binary. 

Statement 00039000 of Figure 3-5: 

IF M0NTHOCURRENT THEN 

checks whether the month information is different than the information currently in the stack. If it 
is, statement 00041000 of Figure 3-5: 

DMDVIN(DSINDX,CM0NTH-1 )*31 ,31 , DATES); 

transfers the Julian dates for the month entered by the user into the 31 -word array DATES. For ex- 
ample , if the user entered 3 , the values 6 1 through 9 1 corresponding to the Julian calendar dates for 
the month of March are transferred from the extra data segment to the array DATES in the stack. 
Data representing the entire month, instead of data representing the specific day entered by the user, 
is transferred by DM0VIN because DMOVIN, which requires considerable time to execute, should be 
used sparingly to maintain programming efficiency. Transferring the data for the entire month saves 
time if the user's next request is for a Julian date in the same month. Note that months are numbered 
from to 11. 

The buffer CURRENT is updated to the current month with statement 00041000 for Figure 3-5: 

CURRENT :=M0NTH; 
The Julian date is computed with statement 00043000 of Figure 3-5: 

JDATE:=DATES(DAY-1>; 
and this information is output to the user . 

The following examples illustrate using the three programs in Figures 3-3, 3-4, and 3-5: 
EXAMPLE 1 : 

: RUN DSINIT 

GENERATE CALENDAR DATA SEGMENT 
ENTER YEAR: 1983 

END DF PROGRAM 
: RUN DSBDSS 

WHEN ALL JULIAN DATE OPERATIONS ARE COMPLETE TYPE: DONE. 
? DONE 

END OF PROGRAM 
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EXAMPLE 2: 

; DATA FIELD .SUPPORT; TERN I 01 

JULIAN DATE CALENDAR 

MONTH = JM_ 

DAY = 31 

DAY = 30 

JULIAN DATE = 335 

MONTH = 2 

DAY = 39 

JULIAN DATE = 60 

MONTH = 6 

DAY = U 

DAY = 13 

JULIAN DATE = 165 

MONTH = 13 

MONTH = 

MONTH = 3 

DAY = 29 

JULIAN DATE = 89 

MONTH = 

EXAMPLE 3: 

: DATA FIELD. SUPPORT; TERM I 02 
JULIAN DATE CALENDAR 

MONTH = 9 

DAY = 1_5 

JULIAN DATE = 259 

MONTH = 7 

DAY = 20 

JULIAN DATE - 202 

MONTH = 8 

DAY = \± 

JULIAN DATE = 227 

MONTH = 5 

DAY = 3 

In Example 1, the command :RUN DS I NIT causes DSINIT to execute. It prints the purpose of the 
program and requests the user to enter the year for which Julian dates are required. When 1983 is 
entered, DSINIT creates an extra data segment, fills an array with Julian dates for the year 1983, 
transfers this data to the extra data segment, and terminates. 

The :RUN DSBOSS command causes DSBOSS to execute. DSBOSS creates and activates two son 
processes (DSACCS) , then suspends itself after the message : 

WHEN ALL JULIAN DATE OPERATIONS ARE COMPLETE TYPE: DONE. 
? 

Example 2 illustrates the SON1 process execution. First a user enters a :DATA statement on a ter- 
minal. (Remember that SON1 and SON 2 have each opened a terminal for input/output.) Then, 
MPE searches the device class directory for a terminal with the formal designator TERM 1 01 and 
allocates the terminal. 
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In response to the month and day requests , the user enters : 

MONTH = 11_ 

DAY = 31 
DSACCS determines that 31 is not a valid day for month 1 1 with statement 00044000 of Figure 3-5 : 

IF JDATE < THEN GO GETDA; 

DSACCS prompts for a new day and the user enters 30; DSACCS computes the Julian date for 
November 30 and displays: 

JULIAN DATE = 335 

Example 3 shows a second user accessing terminal 2. When a user types DONE on $STDIN, (see 
Example 1), the father process terminates, terminating both sons. 

Deleting an Extra Data Segment 

A process can release an extra data segment assigned to it by using the FREEDSEG intrinsic . If the ex- 
tra data segment is private, or if it is a sharable (nonprivate) data segment not currently assigned to 
any other process in the job/session, it is deleted from the entire job/session. If the extra data seg- 
ment is sharable (nonprivate), and currently assigned to any other process in the job/session, it is 
deleted from the calling process , but continues to exist in the job/session . 

For example, to delete a data segment with the logical index contained in INDX, the following intrin- 
sic call could be used : 

FREEDSEGCINDX,0); 

Because the data segment is private to this process, the id parameter is specified as and the segment 
will therefore cease to exist. 

Transferring Data from an Extra Data Segment to the Stack 

A process can copy a block of words from an extra data segment to the stack with the DM0VIN intrin- 
sic. A bounds check is performed by the intrinsic on both the extra data segment and the stack to en- 
sure that the data is taken from within the data segment boundaries and moved to an area within the 
stack boundaries. 

The DM0VIN intrinsic call is illustrated in Figure 3-5 and described earlier in this section. 

Transferring Data from the Stack to an Extra Data Segment 

A process can copy a block of words from the stack to an extra data segment with the DM0V0UT in- 
trinsic. A bounds check is performed by the intrinsic to ensure that the data is taken from an area 
within the stack boundaries and moved to an area within the extra data segment . 

The DMDV0UT intrinsic call is illustrated in Figure 3-3, and described earlier in this section. 
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Changing the Size of an Extra Data Segment 

You can change the current size of an extra data segment with the ALTDSEG intrinsic. In a typical 
application, disc storage for a new segment is obtained by calling the GETDSEG intrinsic. Sufficient 
virtual space is allocated by the system to accommodate the original length of the data segment. This 
virtual space is usually allocated in increments of 512 words (depending on virtual memory con- 
figured in the system configuration). For example, creation of a data segment with a length of 600 
words would result in two increments of 5 1 2 words being allocated for the data segment space , thus 
resulting in 1024 words. 

Once disc storage is obtained, you can use the ALTDSEG intrinsic to reduce the storage required by the 
segment when it is moved into main memory , then later expand it as needed for more efficient use of 
memory. In no case, however, can ALTDSEG be used to increase segment size beyond the virtual space 
originally allocated through GETDSEG. 

The form of the ALTDSEG intrinsic call is: 

ALTDSEGC INDEX, INC, SIZE); 

The parameters specified are : 

index INDEX is a word containing the logical index of the extra data segment, ob- 

tained through the GETDSEG intrinsic call. 

inc INC is the value, in words, by which the extra data segment is to be 

changed. A positive integer value specifies an increase and a negative in- 
teger value specifies a decrease. 

size SIZE is a word to which the new size of the data segment is returned after 

incrementing or decrementing has occurred. 



PROCESS HANDLING CAPABILITY 

All user and system programs under MPE are run on the basis of processes, which are the basic ex- 
ecutable entities in the operating system. Processes are invisible to users with standard MPE 
capabilities. Such users have no control over processes or their structure, since MPE automatically 
creates, handles, and deletes all processes. Users with certain optional capabilities, however, can in- 
teract with processes directly. One of these optional capabilities is Process Handling (PH) which is 
discussed in this section. Process Handling capability, assigned and used independently of the other 
optional capabilities , allows you to : 

• Create and delete processes. 

• Activate and suspend processes . 

• Manage communications between processes. 

• Change the scheduling of processes. 

• Obtain information about existing processes. 

These operations can be very useful to you. For example, they allow you to have several independent 
processes running concurrently on your behalf, all communicating with one another. 
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Processes 

A process is an independent entity that can be run within MPE. Processes are run on behalf of users, 
and on behalf of the operating system. Many processes can be running concurrently. The design of 
MPE is process oriented : the system deals exclusively with processes (except for interrupt routines and 
some very central and specialized system functions). 

A process consists of a private data area (the stack) used only by this process, a Process Control Block 
(PCB) that defines the process, and instructions in a code segment that the process is to execute. Note 
that code segments may be shared by many processes because the segments are not owned by the 
processes. 

When a user enters MPE, a process is created for that user. This process is called a Job/Session Main 
Process (JSMP). The process is linked into the Command Interpreter (CI), which then proceeds to 
handle user commands. 

Every process known to MPE is identified by a number called the Process Identification Number 
(PIN). Most control in MPE is carried out at the process level. A process can run any kind of code 
(such as programs, procedures, private code, sharable code), and one of the main elements needed to 
establish a new process is a starting address (a "program label"). Beginning with the starting address, 
the process follows the sequence of the code until its deletion. 

PROGEN, the "Progenitor" , is the first process established during the initialization phase of MPE. It 
is the responsibility of the Progenitor, using a set of configuration data specified at system configura- 
tion time, to create its "son" processes. These processes are defined as "system" processes, and are 
used to perform parallel functions on behalf of the system. Such processes may include I/O or other 
processes, and in particular the "User Controller Process" (UCOP). All these processes may, if 
required, have their own structure of descendants. 

PROGEN is the ancestor of all processes in MPE, including system processes, as the User Controller 
Process is the ancestor of all user processes currently in existence. The UCOP is consequently the root 
of the user process Tree Structure. The sons of the UCOP are called (User) main processes or the 
JSMPs. 

The father/son relationship between processes is used primarily to maintain control from top to bot- 
tom throughout the structure. In most cases the father is held "responsible" for what happens to its 
son: creation, deletion and other special actions. 

ORGANIZATION OF USER PROCESSES. When you logon (initiate a job or session) , a main process 
is created for you by UCOP. According to the mode of access, the main process can be one of the two 
types: 

• Job Main Process (JMP). 

• Session Main Process (SMP). 

Such a distinction results from the different kinds of control that the system provides for those two 
separate entities: a job is associated with a batch type of access, while a session is for interactive 
access . 

As soon as a given signal is received by UCOP , a JMP or SMP is created (depending upon the origin of 
the signal). The starting address of the JMP or SMP is the Command Interpreter, and once the user is 
validated, the main process is free to recognize any command. 
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ACTIVE AND SUSPENDED PROCESS SUBSTATES. During its life span (that is, between creation 
and deletion), a process finds itself in different substates according to its past and present history, as 
well as its present requirements. Only two of these substates can be controlled by users: active and 
suspended. 

An active process is run by the CPU until it suspends itself, terminates, or is killed. 

A suspended process is not run by the CPU as long as it stays in this substate. In other words, a 
suspended process is waiting for some kind of a signal which will activate it . When it suspends itself , 
a process may specify the origin of its next activation . 

You can programmatically terminate one of your processes. The termination destroys the process and 
all of its descendants , and resets the links of the remaining processes for the session or job . 

Interprocess Communication (IPC) is a facility of the file system which permits multiple user processes 
to communicate easily and efficiently with each other. To accomplish this, IPC uses message files as 
the interface between user processes. These message files act as first -in-first-out queues of records, 
with entries made by FWR I TE and deletions made by FREAD: one process may submit records to the 
file with the FWR I TE intrinsic while another process takes records from the file using FREAD. 

Occasionally a process may attempt to read a record from an empty message file, or write a record to 
a message file that is full. In such situations, the file system will usually cause the process to wait un- 
til its request can be serviced ; that is , until another process either writes a record to the empty file or 
reads enough records to take a block from the full file. 

The flow of information between a given process and a message file is unidirectional. A process open- 
ing the file with read access, identified as a "reader" , may only read from the file, and not write. A 
process opening the file with write access, identified as a "writer", may only write to the file, and 
not read. (If it is necessary for the same process to read and write, it may open the same file twice, 
once as a reader and once as a writer . ) More than one message file may be associated with a process , 
and the process may be configured as a reader to some of the files and as a writer to others. A given 
message file typically has one reader, though more are allowed, and one or more writers. For more 
detail on Interprocess Communication, refer to the MPE File System Reference Manual 
(30000-90236). 

Creating and Activating Processes 

From within any running process, you can programmatically request the creation of a son process 
with the CREATE intrinsic . The CREATE intrinsic loads the program to be run by the new process into 
virtual memory, creates the new process as the son of the calling process, initializes its data stack, 
schedules the process, and returns its Process Identification Number (PIN) to the calling process. 

You can also create processes with the CREATEPROCESS intrinsic. It contains a superset of the 
CREATE intrinsic and, therefore, is more flexible and expandable. CREATEPROCESS allows you to as- 
sign $STDIN and $STDLIST values to a file when the process is created. By using CREATEPROCESS 
you are not limited to the system defaults for $STDINand $STDLIST. 

Once a process is created, it must be activated with the ACTIVATE intrinsic in order to run. When a 
process is activated, it may or may not suspend the process that activated it, then run until it is 
suspended or deleted. A newly created process can be activated only by its father. A father process 
that has been suspended when a son process was activated can be activated only by its son . A father 
process that has been suspended when a son process was activated can be reactivated automatically 
when the son process execution ends, if the flags parameter of the CREATE intrinsic bit is set 
((1 5: 1)=1). A program that has been suspended with the SUSPEND intrinsic can be reactivated by its 
father or any of its sons, as specified in the susp parameter of the SUSPEND intrinsic. 
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Figure 3-6 contains a program which illustrates the CREATE and ACTIVATE intrinsics. Statement 
00027000 reads the name input by the user on $STDIN, and stores the name in the logical array 
NAME. In order to be used in the CREATE intrinsic , the string in the array NAME must be specified in a 
byte array; thus the byte array BNAME is made equivalent to NAME in statement 00008000 in the 
program. Additionally, the string must be terminated by a blank, and statement 00030000 enters 
the ASCII code for a blank character to the end of the string in BNAME. Next, the program displays 
the message: 

CREATE PROCESS 

and calls the CREATE intrinsic with statement 00034000: 

CREATE (BNAME,, PIN,, 1); 

The following parameters were specified in the CREATE intrinsic call. All other parameters were 
omitted in the CREATE intrinsic call : 

progname Specified by BNAME, which contains the name entered by the user. 

entrynarne Omitted; a comma place holder is used. The primary entry point of the 

created process is specified by default. 

pin The Process Identification Number (PIN), to be used by the ACTIVATE in- 

trinsic, is returned to the word PIN. 

param Omitted; a comma place holder is used. A word filled with zeros is 

specified by default. 

flags 1 , which specifies that this (the father) process will be reactivated auto- 

matically by MPE when the created process execution ends (bit(15: 1)=1). 

All other parameters are omitted in the CREATE intrinsic call . 

Statement 00037000: 

FWRITECDUT,ACTMSG,8,0); 
displays the message : 

ACTIVATE PROCESS 

and statement 00039000 of Figure 3-6 calls the ACTIVATE intrinsic to activate the process. The fol- 
lowing parameters were specified : 

pin Specified by PIN, which contains the Process Identification Number of the 

process to be activated , as returned to the CREATE intrinsic by the system . 

susp If susp is specified, the calling process will be suspended when the called 

process is activated. When 2 (bitC 1 4: 1)=1 ) is specified, as in this call, the 
suspended calling process expects to be reactivated automatically by MPE 
when this son process ends execution. If susp had not been specified, the 
calling (father) process would not have been suspended when the called 
process was activated . 
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PAGE 0001 HEWLETT-PACKARD 32100A.08.1 SPL[4W] TUE 


OCT 28, 1982, 4:35 PM 


00001000 


00000 





SCONTROL USLINIT 




00002000 


00000 





BEGIN 




00003000 


00000 


1 


BYTE ARRAY INPUT( : 5 ) : ="INPUT "; 




00004000 


00004 


1 


BYTE ARRAY 0UTPUT(0 : 6 ) : ="0UTPUT " ; 




00005000 


00005 


1 


INTEGER IN,OUT,LGTH,PIN; 




00006000 


00005 


1 


ARRAY REQST[0:8) : =%6412 , "PROGRAM FILE = "; 


00007000 


00011 


1 


ARRAY NAME(0:13) ; 




00008000 


00011 


1 


BYTE ARRAY BNAME(*)=NAME ; 




00009000 


00011 


1 


ARRAY CRMSG(0:6) :="CREATE PROCESS- 




00010000 


00008 


1 


ARRAY ACTMSG(0:7) :="ACTIVATE PROCESS"; 


00011000 


00010 


1 


DEFINE CCL=IF < THEN QUIT#, 




00012000 


00010 


1 


CCG=IF > THEN QUIT*, 




00013000 


00010 


1 


CCNE=IF <> THEN QUIT*; 




00014000 


00010 


1 






00015000 


00010 


1 


INTRINSIC FOPEN.FREAD.FWRITE, CREATE, ACTIVATE , QUIT ; 


00016000 


00010 


1 






00017000 


00010 


1 


<<END OF DECLARATIONS>> 




00018000 


00010 


1 






00019000 


00010 


1 


IN:=FOPEN(INPUT,%45); 


<<$STDIN>> 


00020000 


00007 


1 


CCL(l); 


<<CHECK FOR ERROR >> 


00021000 


00012 


1 


OUT : =FOPEN(OUTPUT , %414 , 1 ) ; 


<<STDLIST>> 


00022000 


00022 


1 


CCL(2); 


<<CHECK FOR ERROR>> 


00023000 


00025 


1 






00024000 


00025 


1 


NEXT: 




00025000 


00025 


1 


FWRITE(OUT,REQST,9,%320) ; 


<<REQUEST PGM FILE NAME>> 


00026000 


00032 


1 


CCNE(3) ; 


<<CHECK FOR ERROR>> 


00027000 


00035 


1 


LGTH:=FREAD(IN,NAME,-26) ; 


<<INPUT FILE NAME>> 


00028000 


00043 


1 


CCNE(4) ; 


<<CHECK FOR ERROR>> 


00029000 


00046 


1 


IF LGTH=0 THEN GO EXIT; 


<<IF NO NAME - EXIT>> 


00030000 


00053 


1 


BNAME(LGTH) ; =%40 ; 


<<SET IN TRAILING BLANK>> 


00031000 


00056 


1 






00032000 


00056 


1 


FWRITE(0UT,CRMSG,7,0); 


<<CREATE MESSAGE>> 


00033000 


00063 


1 


CCNE(5) ; 


<<CHECK FOR ERROR>> 


00034000 


00066 


1 


CREATE (BNAME, ,PIN, ,1) ; 


<<CREATE PROCESS>> 


00035000 


00076 


1 


CCL(6); 


<<CHECK FOR ERROR>> 


00036000 


00101 


1 






00037000 


00101 


1 


FWR ITE ( OUT , ACTMSG ,8,0); 


<< ACTIVATE MESSAGE >> 


00038000 


00106 


1 


CCNE(7) ; 


<<CHECK FOR ERROR>> 


00039000 


00111 


1 


ACTIVATE (PIN, 2); 


<<ACTIVATE PROCESS) > 


00040000 


00115 


1 


CCL(8); CCG(9); 


<<CHECK FOR ERROR>> 


00041000 


00123 


1 


GO NEXT; 


<<CONTINUE 0PERATIONS>> 


00042000 


00130 


1 


EXIT:END. 




PRIMARY 


DB STORAGE=%013; SECONDARY DB STORAGE =%0OO55 


NO. ERR0RS=000 


NO. WARNINGS=000 




PROCESSOR TIME=C 


:00:04; ELAPSED TIME=0 :00 : 51 ; 





Figure 3-6. Using the CREATE and ACTIVATE Intrinsics (Program PROG) 
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A sample run of the program listed in Figure 3-6: (named PROG) results in the following: 

: RUN PROG 

PROGRAM FILE = SPL.PUB.SYS 
CREATE PROCESS 
ACTIVATE PROCESS 

HEWLETT-PACKARD 321 00A. 08.1 SPLC4W] TUE, OCT 28, 1982, 4:35 PM 

> $C0NTRQL USLINIT 
>BEGIN 

> ARRAY MSG(Q:12):="» TEST PROCESS EXECUTING »"; 

> INTRINSIC PRINT; 

> PRINT CMSG,13,0); 

> END. 
PRIMARY DB STORAGE=%001 ; SECONDARY DB STORAGE=X00015 
NO. ERRORS=000; NO. WARNINGS=000 

PROCESSOR TIME«0:00:02 ELAPSED TIME=0: 13:20 



PROGRAM FILE * SEGDVR.PUB.SYS 

CREATE PROCESS 

ACTIVATE PROCESS 

SEGMENTER SUBSYSTEM CC.O) 

-U5L $0LDPASS 

- PREPARE $NEMPASS 

- EXIT 

PROGRAM FILE = $QLDPASS 

CREATE PROCESS 

ACTIVATE PROCESS 

» TEST PROCESS EXECUTING * 

PROGRAM FILE = [return) 

END OF PROGRAM 



When SPL.PUB.SYS is entered in response to the "PROGRAM FILE- " request, the program displays: 

CREATE PROCESS 

ACTIVATE PROCESS 

then suspends itself and the SPL compiler subsystem is accessed. (This process has been created and 
activated because of the SPL . PUB . SYS response by the user.) 

A short program is entered from the terminal and the SPL compiler is exited, reactivating PROG at 
the statement following the ACTIVATE intrinsic call, and causing the "PROGRAM FILE- " message to 
be displayed again. 
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The response : 

SEGDVR.PUB.SYS 

causes PROG to create and activate the Segmenter Driver (a programmatic entry point to the 
Segmenter subsystem). The Segmenter displays the following and a prompt (-): 

SEGMENTER SUBSYSTEM CC.O) 

The small program written in SPL and compiled into the USL file $0LDPASS (the default USL file 
since a uslfile parameter could not be included in the SPL. PUB. SYS response) is identified with the 
Segmenter command: 

- USL $0LDPASS 
The next command : 

- PREPARE SNEHPASS 
prepares the SPL program and the Segmenter is exited with the command: 

- EXIT 

Once again, PROG is reactivated and requests a program file to be created and activated. The 
response "$0LDPASS" causes the compiled and prepared program written in SPL to be created and 
activated . 

This program executes and displays : 

*TEST PROCESS EXECUTING* 

then ends execution, reactivating PROG. 

A [RETURN) (signifying no input) is entered in response to the "PROGRAM FILE* " request and the 
program terminates. 

The example below uses PROG to create and activate a duplicate of itself : 

: RUN PROG 

PROGRAM FILE - PROG 
CREATE PROCESS 
ACTIVATE PROCESS 

PROGRAM FILE = PROG 
CREATE PROCESS 
ACTIVATE PROCESS 

PROGRAM FILE = [RETURN] **3** 



PROGRAM FILE = [RETURN! **2*# 
PROGRAM FILE = [RETURN) **1** 
END OF PROGRAM 
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When PROG is entered in response to the "PROGRAM FILE= " request, the calling process (PROG) 
creates a duplicate of itself and activates this process (for clarity, call this PROG1). This process ex- 
ecutes and requests a file name . The user enters PROG again , causing yet another duplicate (call this 
one PROG2) to be created and activated. At this point, PROG is suspended: it has created and ac- 
tivated a duplicate process. The duplicate process (PROG1) has, in turn, created and activated a 
duplicate of itself (PROG2). Thus, it also is suspended. 

The third process (PROG 2) executes and displays: 

PROGRAM FILE = 



A carriage return (see [RETURN] **3** in the example) causes this process to stop executing and control 
returns to PROG 1 . PROG 1 displays : 

PROGRAM FILE = 

A second carriage return (see [RETURN 1 **2** in the example) causes this process to stop executing and 
control returns to PROG. 

PROGRAM FILE = is displayed once more, this time by the original process. Another carriage return 
(see [RETURN) **i#* in the example) causes PROG to stop executing and control returns to the session 
main process , which displays : 

END OF PROGRAM 



Suspending Processes 

A process can suspend itself with the SUSPEND intrinsic. When this is done, the process relinquishes 
its access to the central processor until reactivated by an ACTIVATE intrinsic call. When it suspends 
itself, the process must specify the anticipated source of this ACTIVATE call (its father or son process). 
When the process is reactivated, it begins execution with the instruction immediately following the 
SUSPEND intrinsic call. The SUSPEND intrinsic can also release a local Resource Identification 
Number (RIN) when the process is suspended by specifying the RIN as a parameter in the intrinsic 
call. 

The intrinsic call : 

SUSPENDC3.RINNUM); 

would cause the process to suspend itself and release the local RIN specified by RINNUM. The parame- 
ter 3 (bit ( 1 4 : 1 )= 1 and bit ( 1 5 : 1 )= 1 ) specifies that the process expects to be reactivated by its father 
or one of its sons. 

Deleting Processes 

A process can delete itself with the TERM I NATE intrinsic , or delete of any of its sons with the K I LL 
intrinsic . When this is done , all code and data segments in the process and all resources owned by the 
process are released; all files opened by the process are closed; and finally, the Process Identification 
Number (PIN) is released. When a process is deleted, MPE also automatically deletes all descendants 
of that process, as shown in Figure 3-7. Within a process tree structure, the newest generations are 
deleted first. Within each generation, processes are deleted in the order of their creation. 
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FIRST (OLDEST) 
GENERATION 



SECOND 
GENERATION 



THIRD 
GENERATION 



FOURTH (NEWEST) 
GENERATION 




(WHEN PROCESS 2 IS DELETED, THE FOLLOWING STRUCTURE REMAINS.) 



FIRST 
GENERATION 



SECOND 
GENERATION 




Figure 3-7. Process Deletion 
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In the job or session main process, the TERMINATE intrinsic is invoked automatically by detection of 
an end-of- job/session condition. This intrinsic removes the job or session from the system. 

Interprocess Communication 

You can direct the communication of information between processes. This information transfer, 
however, is restricted to upward or downward paths through the process tree structure, so that any 
process can communicate only with its father or sons. Between any father/son pair, only one such 
transfer is allowed at any particular time. This feature should not be confused with message files, 
which can be used to transfer information between unrelated processes. 

Information transferred between processes is referred to as "mail". It is sent from one process to 
another through an intermediate storage area called a "mailbox". At any given time, a mailbox can 
contain only one item of mail (a "message"). For any process, there are two sets of mailboxes: 

• The mailbox used for communication between the process and its father. Each process has one of 
these. 

• The set of mailboxes used for communication between the process and its sons. Each process has 
one of these mailboxes for each of its sons. 

Even though there are two sets of mailboxes, there is only one mailbox between any two processes. 

The transfer of mail is based upon a transaction between the sending and receiving processes that in- 
volves the following steps: 

1. Optionally, the sending process may test the mailbox to determine its status (whether it is 
empty, contains a message, or is being used by the receiving process). 

2. The sending process transmits the mail to the mailbox. The message transferred is a word array 
in the sending process stack, defined by a starting location and word count. The smallest mes- 
sage allowed is a single word. MPE automatically performs a bounds check to ensure that the 
array specified actually falls within the limits of the process stack. 

3. The receiving process optionally may test the mailbox to determine its status. 

4. If the mailbox contains a message, the receiving process collects this mail. If the mail is not col- 
lected, it is overwritten by additional mail from the sending process. When the mail is collec- 
ted, another bounds check is performed to validate the address given for the stack of the receiv- 
ing process. 
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TESTING MAILBOX STATUS. A process can determine the status of the mailbox used by its father 
or by a son with the MAIL intrinsic. If the mailbox contains mail that is awaiting collection by this 
process, the length of the message, in words, is returned to the calling process. This enables the call- 
ing process to initialize its stack in preparation for receipt of the message. 

For example, to test the status of the mailbox associated with one of its son processes, the following 
intrinsic call could be used : 

STATCOUNT:=MAILCSaNPIN,MCDUNT); 

SONPIN contains the Process Identification Number (PIN) of the son process. An integer count sig- 
nifying the length, in words, of the incoming message will be returned to the word MCOUNT. The 
status returned to STATCOUNT will be one of the following values: 

Status Meaning 

The mailbox is empty . 

1 The mailbox contains previous outgoing mail from this calling process that has not 
yet been collected by the destination process. 

2 The mailbox contains incoming mail awaiting collection by this calling process. 
The length of the mail is returned in MCDUNT. 

3 An error occurred because an invalid PIN was specified or a bounds check failed. 

4 The mailbox is temporarily inaccessible because other intrinsics are using it in the 
preparation or analysis of mail. 

SENDING MAIL. A process sends mail to its father or sons with the SENDMAIL intrinsic. If the 
mailbox for the receiving process contains a message sent previously by the calling process but not col- 
lected by the receiving process, the action taken depends on the wait flag parameter specified in 
SENDMAIL. If the mailbox is currently being used by other intrinsics, the SENDMAIL intrinsic waits 
until it is free and then sends the mail. 

For example , to send mail to its father , the following intrinsic call could be used : 

STAT: =SENDMAILCO, 3, LDCAT,WAITSTAT) ; 

The parameters specified are : 

pin 0, specifying that the mail is to be sent to the father process. 

count 3, specifying that the length of the message is three words. 

location LOCAT, a logical array in the stack containing the message to be sent. 

tiaitflag HAITSTAT, a logical word. If bit (1 5:0)=1 , any mail sent previously will 

be overwritten . If bit (15:1)=1, the intrinsic will wait until the receiving 
process collects the previous mail before sending the current mail . 
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The status returned to STAT is one of the following values : 
Status Meaning 

The mail was transmitted successfully. The mailbox contained no previous mail. 

1 The mail was transmitted successfully. The mailbox contained previously sent mail 
that was overwritten by the new mail, or contained previous incoming/outgoing 
mail that was cleared . 

2 The mail was not transmitted successfully because the mailbox contained incoming 
mail to be collected by the sending process (regardless of the waitflag parameter 
setting). 

3 An error occurred because an illegal pin was specified, or a bounds check failed. 

4 An illegal wait request would have produced a deadlock. 

5 The request was rejected because the count specified in the count parameter ex- 
ceeded the mailbox size allowed by the system. If this size exceeds one word, then 
the maximum size cannot exceed the maximum DST size for the system. 

6 The request was rejected because storage resources for the mail data segment were 
not available. 

RECEIVING (COLLECTING) MAIL. A process collects mail transmitted from its father or a son 
with the RECEIVEMAIL intrinsic. If the mailbox for the receiving process is empty, the action taken 
depends on the waitflag parameter specified in RECEIVEMAIL. If the mailbox is currently being used 
by other intrinsics, the RECEIVEMAIL intrinsic waits until the mailbox is free before accessing it. 

To collect a message from a son process, the following intrinsic call could be used: 

STAT:=RECEIVEMAILCSONPIN,MDATA,WAITSTAT); 

The parameters specified are : 

P^tt SDNPIN, which contains the Process Identification Number of the son 

process (0 for father process). 

location MDATA, a logical array in the stack in which the incoming mail will be 

stored . 

Waitflag WAITSTAT, a logical word. If bit (1 5: 1 )-l , the intrinsic will wait until the 

incoming mail is ready for collection. If bit (15:0)=1, the intrinsic will 
return to the calling process immediately. 
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One of the following status codes is returned to STAT: 
Status Meaning 

The mailbox was empty (and WAITSTAT bit (1 5 : 1 )=0). 

1 No message was collected because the mailbox contained outgoing mail from the 
receiving process. 

2 The message was collected successfully. 

3 An error occurred because of an illegal pin or a bounds check failed. 

4 The request was rejected because waitflag specified that the receiving process 
should wait for mail if the mailbox is empty, but the other process sharing the 
mailbox is already suspended, waiting for mail. If both processes were suspended, 
neither could activate the other, and they may be deadlocked. 

Avoiding Deadlocks 

Simultaneous use of mail -transmission, process-suspension, and RIN-locking intrinsics throughout a 
process structure could result in a deadlock if the intrinsic calls are not synchronized properly. Be 
aware of the following : 

1 . In a multi -process job/session, whenever a process is suspended (through the SUSPEND intrinsic, 
or when locking a RIN or receiving mail), MPE does not determine whether all other processes 
in the tree are suspended. Avoid this situation. 

2. An attempt by a process to lock a global RIN succeeds only if both the following conditions are 
met: 

a. No other process within the job/session currently has locked this RIN. A global RIN can- 
not be used as a local RIN, because deadlock within the same job/session can occur. 

b. The calling process currently has no other global RIN locked for itself. This could other- 
wise result in deadlock between two jobs/sessions. 

Rescheduling Processes 

When a process is created, it is scheduled on the basis of a priority class assigned by its father. After 
this point, its priority class can be changed at any time with the GETPRIDRITY intrinsic. A process 
can change its own priority or that of a son, but it cannot reschedule its father. 

Generally, MPE schedules processes in linear or circular subqueues, as described in the HP 3000 
Computer Systems General Information Manual (5953-7553). The standard linear subqueues are: 

• The ASsubqueue, containing system processing only. 

• The BS subqueue, containing processes of very high priority. 
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The circular subqueues are : 

• The CS subqueue, recommended for interactive processes. 

• The DS subqueue, available for general use at a lower priority than the CS subqueue, and recom- 
mended for jobs (batch). 

• The ES subqueue operates at very low priority (background). 

The subqueue to which a process belongs determines the priority class of the process. From highest to 
lowest priority, these classes (named after their subqueues), are: 

AS 
BS 
CS 
DS 
ES 

To reschedule itself with the priority class DS, a process would make the following call: 
GETPRIDRITY (0,"DS"); 

The parameter specifies that the calling process is rescheduling itself. If the process were reschedul- 
ing a son process, the Process Identification Number (PIN) of the son processes would be specified. 

Determining Source of Activation 

After a suspended process is reactivated, it can determine whether the source of the activation request 
was its father process or one of its son processes with the GETORIGIN intrinsic call. 

For example, the following intrinsic call could be used: 

SOURCE: =GETORIGIN; 

One of the following codes could be returned to SOURCE: 

1 Indicating that the process was activated by its father. 

2 Indicating that the process was activated by a son . 

Determining Father Process 

A process can determine the Process Identification Number of its father with the FATHER intrinsic. 

The Process Identification Number of the father is returned to PIN. For example, the following in- 
trinsic call could be used : 

PIN:=FATHER 
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Determining Son Processes 

A process can request the return of the Process Identification Number assigned to any of its sons with 
the GETPRDC ID intrinsic. 

For example , the following intrinsic call would return the Process Identification Number of the sixth 
existing son of the calling process to the word PINNUM: 

PINNUM:=GETPRDCID(6); 

Determining Process Priority and State 

A process can request the return of a double -word message denoting the following information about 
its father or sons with the GETPRDC INFO intrinsic (refer to the GETPROCINFO discussion in Section II). 
For example, to request information about its father, the following intrinsic call could be used: 

INFO:=GETPROCINFO(0); 

The parameter specifies that the process is the father. If the process is a son process, the Process 
Identification Number of the son process is specified. 

The information returned to the double-word INFD is of the following form: 
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Not Used 



Activity 
State 



ACTIVATE 
Origin 



Suspension 
Conditions 



The information is interpreted as follows for the father process: 
Word Bits Value Meaning 

00011110 Process has priority 3 in Master Queue . 
00000000 Not used. 



1 



(8:8) 

(0:8) 

(15:1) 

(14:1) 

(13:1) 

(9:4) 

(7:2) 

(4:3) 



Process is suspended. 

Would not expect the source of activation to be the father. 

1 The source of expected activation is the son. 

0000 Not used. 

01 Origin of last ACTIVATE call was father of this process. 
100 Circular subqueue. 
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RESOURCE MANAGEMENT 



Any element of the HP 3000 which a program can access through MPE is called a resource. A 
resource can be an input or output device, a file, subroutine, procedure, code segment, or the data 
stack. 

Occasionally , you may want to manage a specific resource shared by a set of jobs or processes , so that 
no two jobs or processes can use the resource at the same time. To accomplish resource management 
within a job or session, or between processes, the jobs or processes must cooperate. For example, if 
Job B must not access a particular file when Job A is using it , both jobs should contain provisions for a 
"hand -shaking" arrangement overseen by MPE when both jobs are active. Job B will be denied access 
to the file while Job A is accessing it, or be suspended until Job A releases its exclusive access. 

Under this arrangement, when Job A has exclusive access to the file, when Job B attempts to access 
the same file, access will be denied, and Job B will be suspended until Job A releases its exclusive ac- 
cess. Then Job B can resume execution and access the file. However, if Job B has been suspended by 
MPE, it is unable to access the file and in fact cannot execute at all. 

The hand-shaking arrangement is based on an arbitrary Resource Identification Number (RIN) made 
available to users (for inter- job management) or assigned to the job (for inter-process management). 
Within their jobs or processes, cooperating programmers relate a RIN to a particular resource through 
the statement structure of the job or process. When a job or process seeks exclusive access to a 
resource , it requests MPE to lock the RIN associated with the resource . The request is granted only if 
no other job or process has already locked the RIN. Otherwise, the requesting process is suspended 
until the RIN is released. When it is finished with the resource, the job or process requests MPE to 
unlock the RIN so that others can lock it. 

A RIN is not a physical entity, nor is it logically assigned to any resource. The association of a RIN 
and a resource is accomplished only by the structure of the code which operates the job or process 
which uses the RIN. The RIN number is always known to MPE, but the resource with which it is as- 
sociated is not. For this reason, all cooperating programs must specify what RIN is associated with 
which resource. 

Processes run by users with standard MPE capabilities can lock only one global RIN (used at the 
unrelated -process level) at a time. Users with Multiple RIN (MR) capability can lock more than one 
global RIN at a time . 

Users with Multiple RIN (MR) capability, must avoid deadlocking, which occurs when two or more 
suspended processes cannot resume because they are mutually blocked. For example, you have two 
processes A and B, and two RINs 1 and 2. Each process attempts to lock both RINs in the following 
sequence: Process A tries to lock RIN 1 then RIN 2, and Process B tries to lock RIN 2 then RIN 1. 
Process A will lock RIN 1 then have to wait for RIN 2 to be released by Process B and Process B will 
lock RIN 2 and have to wait for Process A to release RIN 1 before it can continue. The processes are 
mutually blocked and thus a deadlock has occurred. 

Deadlocks can be avoided by ranking. If the RINs had been ranked (for example, ranking order A=l ; 
B=2), then Process B should have tried to lock RIN 1 before RIN 2. However, since Process A already 
locked RIN 1 , Process B would have to wait until Process A had released RIN 1 and locked RIN 2 
which in this example would be free. A WARMSTART is necessary to free the locked processes. 
Ranking also applies to processes and procedures . 
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Inter -Job Level (Global) RINs 

The RINs used at the inter-job level are called "global" RINs. Global RINs prevent simultaneous ac- 
cess to a resource by two or more processes. Each global RIN is a positive integer which is unique 
within MPE. Global RINs are acquired and released through MPE commands, and locked and un- 
locked through MPE intrinsics. 

ACQUIRING GLOBAL RINS. Before users can engage in cooperative resource management through 
a RIN, one user must request the RIN and assign it a RIN password that enables all who know the 
password to lock the RIN. This is done with the : GETR I N command : 

:GETRIN rinpassaord 

where rinpassword is a required password of up to eight alphanumeric characters, beginning with a 
letter, which locks the RIN. 

The : GETR IN command is typically entered during a session. As a result of the command, MPE 
makes a RIN available for use, and displays the RIN number in the form: 

RlHzrinnum 

The user who enters the : GETR IN command can use the RIN to lock and unlock the resource in the 
current session, or in future jobs and sessions. The RIN and its password are passed to other users to 
permit them to lock and unlock the resource in their jobs and sessions. All users do this by including 
the RIN as a reference parameter in intrinsic calls that lock and unlock resources. Users can use the 
RIN until the user who issued the : GETR IN command for that resource releases the RIN. 



NOTE 



MPE regards the user who issues the : GETR IN command 
as the owner of the RIN. Only the owner of a RIN can 
release it . 



The total number of RINs that MPE can handle is specified when the system is configured, but can 
never exceed 1024. 

Refer to the MPE V Commands Reference Manual (32033-90006) for details on the :GETRIN 
command. 
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RELEASING GLOBAL RINS. The owner of a global RIN (the user who issued the :GETRIN 
command) can release the RIN to the RIN pool managed by MPE. Only the owner can release the 

To release a RIN, enter the command: 

: FREER IN rin 
where rin is the RIN to be released . 

Refer to the MPE V Commands Reference Manual (32033-90006) for details on the :FREERIN 
command. 

LOCKING AND UNLOCKING GLOBAL RINS. Any global RIN assigned to a group of users can be 
locked by one process at a time with the L0CKGL0RIN intrinsic. Once a RIN is locked, any attempt 
by another process to lock this RIN fails. Note that depending on the call, the calling process may be 
suspended until the RIN is released. 

To lock a global RIN, a user must know the rinpassword specified with :GETRIN, and its number 
returned by :GETRIN. Users with standard MPE capability can lock only one global RIN at a time. 

The L0CKGL0RIN intrinsic is useful when locking an entire file would inconvenience other users. For 
example, if several users are trying to access and update a large file simultaneously, one will succeed 
in locking the file and the others will be suspended until the file is unlocked. The LDCKGLORIN in- 
trinsic, however, lets users lock a portion of a file so that other users are suspended less often. 

The UNLDCKGLORIN intrinsic does not check whether the rinnum parameter specifies the most recently 
locked global RIN. When global RINs are locked and unlocked in any order by concurrent processes, 
deadlocks can occur. An effective way to avoid deadlocks is to assign a rank to each RIN which is 
used by all processes locking them. 

Figure 3-8 shows a program using the L0CKGL0R I N and UNLOCKGLQRINintrinsics. The program al- 
lows a user to lock four records, as a RIN, in a file so that a record can be updated without chance of 
another user updating it simultaneously. In the program, the other users are not suspended when at- 
tempting to access records elsewhere in the file. 

The file B00KFILE, illustrated in Figure 3-9, contains the titles and status of the 20 books in a 
library. The program of Figure 3-8 will access this file. 

B00KF I LE contains 20 records, so the program must acquire five RINs (the program uses four records 
per RIN). This is accomplished by issuing the command: 

:GETRIN BD0KRIN 

where B00KRIN is the rinpassword specified in the program to lock the RIN. (See statements 
00006000 through 00032000 in Figure 3-8.) 
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TT-PACKARD 32100A.08 
$C0NTR0L USLINIT 
BEGIN 

ARRAY 

ARRAY 

ARRAY 

ARRAY 
IN 



1 SPL[4W] TUE, OCT 28, 1982, 4:35 PM 



INPUT{0:5) -"INPUT " 
0UTPUT(0:6) :="0UTPUT 
NAME(0:8) := 
PASSWD(0:7) 
OUT, BOOK, 



BOOKFILE "; 
="BOOKRIN "; 
LGTH, ACCNO, 



BYTE 
BYTE 
BYTE 
BYTE 

INTEGER IN, OUT, BOOK, LGTH, ACCNO, RIN; 
LOGICAL DUMMY, COND:=TRUE; 
ARRAY BUFR(0:35); 
BYTE ARRAY BBUFR(*) =BUFR ; 

ARRAY HEAD(0:13):s"LIBRARY INFORMATION PROGRAM."; 
ARRAY REQUEST(0:7):=%6412, "ACCESSION NO: "; 
ARRAY CHANGE (0 :9 ) :=" NEW LOCATION: " ; 
EQUATE RINBASE=2, RECDS ' PER 'RIN=4, MAXRIN=6; 
DEFINE CCL =IF < THEN QUIT#, 
CCNE=IF <> THEN QUITS; 
INTRINSIC FOPEN , FREAD , FWRITE , FCONTROL , FREADDIR , FWR ITE 
LOCKGLORIN , UNLOCKGLORIN , QUIT , BINARY ; 
<<END OF DECLARATIONS>> 

IN:=F0PEN(INPUT,%45); CCL(l); 

OUT: =F0PEN(0UTPUT,%414) ; CCL(2) ; 

BO0K:=FOPEN(NAME,%5,%304) ; CCL(3) 

FWRITE (OUT, HEAD, 14 ,0 ) ; CCNE(4); 



<<$STDIN>> 
<<$STDLIST>> 
<<0LD DISC FILE>> 
<<PROGRAM ID>> 



LOOP: 



FWRITE(OUT, REQUEST, 8, %320) ; CCNE(5) ; 
LGTH:=FREAD(IN,BUFR,-10) ; CCNE(6); 
IF LGTH=0 THEN GO EXIT; 
ACCNO : =BINARY (BBUFR , LGTH ) ; 
F <> THEN GO LOOP; 

RIN:=RINBASE+(ACCNO/RECDS'PER'RIN); 
IF NOT(RINBASE<=RIN<=MAXRIN) THEN GO 
LOCKGLORIN( RIN, COND.PASSWD) ; 



<<REQUEST BOOK N0>> 
<<INPUT NUMBER>> 
<<N0 INPUT-EXIT>> 
<<C0NVERT NUMBER>> 
<<IF BAD TRY AGAIN>> 
<<COMPUTE RIN N0>> 
LO0P;<<BNDS CHK RIN>> 
<<LOCK FILE SUBSET>> 



FREADDIR(B0OK,BUFR,36,DOUBLE(ACCNO));CCL(7) ;<<READ DATA>> 



<<EOF, TRY AGAIN>> 
<<DISPLAY DATA>> 
<<REQUEST A CHANGE>> 



IF > THEN GO AGAIN; 
FWRITE(OUT,BUFR,36,0) ; CCNE(8); 
FWR ITE (OUT, CHANGE, 10, %320) ; CCNE(9) ; 
BUFR (19):=" "; 
MOVE BUFR(20) :=BUFR(19) , (16); 
LGTH : "FREAD ( IN , BUFR ( 19 ) , 17 ) ; CCNE ( 10 ) 
IF LGTH>0 THEN 
BEGIN 

FWRITEDIR (BOOK, BUFR, 36 .DOUBLE (ACCNO)) ;<<MODIFY FILE>> 



<<BLANK OLD LOCN>> 
<<READ NEW LOCN>> 
<<NEW LOCN ENTERED>> 



CCNE (11); 
END; 
FCONTROL (BOOK, 2, DUMMY ) ; CCL (12) 



AGAIN: 

UNLOCKGLORIN(RIN) 

GO LOOP; 
EXIT:END. 



CCNE (13) ; 



<<CHECK FOR ERROR>> 

<<FORCE RECD POST>> 

<<UNLOCK SUBSET>> 
<<CONTINUE>> 



Figure 3-8. Using the LOCKGLORIN and UNLOCKGLORIN Intrinsics. 
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TITLE: THE BORROWERS 
TITLE: ALICE IN WONDERLAND 
TITLE: PETER PAN 
TITLE: JUNGLE BOOK 
TITLE: THE LIFE OF MERENB 
TITLE: INTRO TO TAI CHI CHUAN 
TITLE: TOM SAWYER 
TITLE: TREASURE ISLAND 
TITLE: A CHRISTMAS CAROL 
TITLE: THE WIZARD OF OZ 
TITLE: THE DARK CRYSTAL 
TITLE: SPEED RACER 
TITLE: ULTRAMAN GOES TO TOWN 
TITLE: H.M.S. PINAFORE 
TITLE: FEAR OF FLYING 
TITLE: SNOW WHITE 
TITLE: DR. DOOLITTLE 
TITLE: TALES OF MOTHER GOOSE 
TITLE: AESOP'S FABLES 
TITLE: THE GULAG ARCHIPELAGO 
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Figure 3-9. 

The program in Figure 3-8 establishes the RIN number limits 2 and 6 (statement 00014000), thus 
using only RINs 2, 3, 4, 5, and 6. MPE returns the RIN number assigned each time the :GETRIN 
command is entered. Because MPE does not always assign RINs in sequence, and because the program 
wants consecutive RINs to keep track of them more easily, it may be necessary to enter more 
:GETRIN commands before the program is run to acquire the five consecutive RINs. Extra RINs can 
be released with the : FREER IN command. 

The statement: 

FWRITECOUT, REQUEST, 8,%320);CCNE(5); 

requests a book number from the user and performs a condition code check. Note that in statement 
00016000 Figure 3-8, CCNE has been defined as: 

IF <> THEN QUIT*; 

This eliminates the need to repeat the entire statement at every point in the program where a condi- 
tion code check is required. Instead, the statement CCNE and an arbitrary number (5) can be used. 

The book number is read with the statement : 

LGTH:=FREADCIN,BUFR,-10); 
and converted to a binary value with the statement : 

ACCND : «B I NARY (BBUFR , LGTH ) ; 
The RIN to be locked is computed with the statement : 

RIN:=RINBASE+CACCNO/RECDS'PER'RIN); 
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RINBASEand RECDS'PER'RIN have been equated to 2 and 4, respectively (see statement 00014000 
of Figure 3-8). Thus, if a book number 3 is entered by the user, the RIN number to be locked would 
be RIN 2, computed in the following way (using integer division): 

RIN = 2 + (3/4) 

= 2 + 

The record specified by the book number is displayed for the user and the "NEW LOCATION:" is 
requested. The existing location information is filled with blanks with statements 00037000 and 
00039000: 

BUFR(19):=" "; 

MOVE BUFRC20):=BUFR(19),C16); 
The new location is entered and read with the statement : 

LGTH:=FREAD(IN,BUFRC19),17); 
and the record is updated with the statement : 

FWRITEDIR(BOOK,BUFR,36,D0UBLE(ACCN0>); 
In case the opened file is a buffered file , the statement : 

FC0NTR0L (BOOK, 2, DUMMY) ; 

ensures that the process buffers are posted to disc before the RIN is unlocked. 

In this type of program , it is important that the number of records per block be equal to the number 
of records per RIN. The RIN must contain a complete block of records. 

The statement : 

UNLOCKGLORIN(RIN); 

unlocks the RIN before the loop is repeated. When the user enters a new book number, a new RIN 
will be computed and locked. 



When [RETURN] is pressed, signifying no input, the program terminates. 
The results of the program in Figure 3-8 are shown below: 

: RUN LIBIN 

LIBRARY INFORMATION PROGRAM. 

ACCESSION NO: 3 

TITLE: JUNGLE BOOK L0CN: AVAILABLE 

NEW LOCATION: FACULTY LOAN - DR. JOHNSON 
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ACCESSION NO: 1^ 

TITLE: THE DARK CRYSTAL LDCN: AVAILABLE 

NEW LOCATION: LOANED CARD* 451, DUE APRIL 1 

ACCESSION NO: 3 

TITLE: JUNGLE BOOK LOCN: FACULTY LOAN - DR. JOHNSON 

NEW LOCATION: 

ACCESSION NO: 9 

TITLE: THE WIZARD OF OZ LDCN: AVAILABLE 

NEW LOCATION: INTERLIBRARY LOAN - UNIV. OF OZ 

ACCESSION NO: 3 

TITLE: JUNGLE BOOK LOCN: FACULTY LOAN - DR. JOHNSON 

NEW LOCATION: AVAILABLE 

ACCESSION NO: (RETURN! 
END OF PROGRAM 



Interprocess (Local) Level RINs 

Interprocess RINs are called local RINs. Local RINs are used to prevent simultaneous access of a 
resource by two or more processes within the same job. Each local RIN is a positive integer that is 
significant to processes within the job only. 

Local RINs are assigned, managed, and released with the GETLDCRIN, LOCKLOCRIN and 
FREELOCRIN intrinsics . 

ACQUIRING LOCAL RINS. Like global RINs, local RINs must be acquired by the user before they 
can be used by the processes within a job. For example : 

GETL0CRINC6); 

would acquire six local RINs, 1 through 6. Multiple RIN (MR) capability is not required and it is the 
user's responsibility to avoid deadlocks. 

LOCKING AND UNLOCKING LOCAL RINS. Any local RIN assigned to a job can be locked by one 
process at a time, by using the LOCKLOCRIN intrinsic call within that process. When this is done 
other processes within the job that attempt to lock this RIN are suspended until the locked RIN is 
released. 

For example, to lock RIN number 6 (acquired by GETLOCRIN) unconditionally, the following call 
could be used : 

L0CKL0CRINC6,C0ND); 

Unconditional locking is denoted when bit (15: 1)=1 of the logical word COND. If bit (1 5 : 1 )=0 lock- 
ing will take place only if the RIN is immediately available. ' 
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To unlock the same RIN, the intrinsic call: 
UNLOCKLOCR I NC6); 

could be used. The call above makes RIN number 6 available for locking by other processes in the 
job. The highest priority process suspended because this RIN was locked is now activated. 

To illustrate how the LOCKLOCRINand UNLOCKLOCR IN intrinsic calls are used, consider two processes, 
a father and its son, within a job: 



FATHER PROCESS 



SON PROCESS 



LP:=FOPENCLIN,...); 



LP:=FOPENCLIN,...); 



GETL0CRINC3); 

FWRITECLP,...); 

L0CKL0CRINC1 ,TRUEVAL); 
CREATE CDESCEND,...); 
FWRITECLP,...); 

• 

UNLOCKLOCR I NC1); 



L0CKL0CRINC1 ,TRUEVAL); 
FWRITECLP,...); 



FWRITECLP,...); 



UNL0CKL0CRINC1); 



Suppose the father and son processes wanted to use RIN 1 to manage the line printer (designated as 
LP) so that the son process could never use the printer while the father is using it. This is coded in 
the examples above. When the father first references LP, the son has not been created and the print- 
er need not be locked. But just before creating the son, the father locks the printer RIN. The father 
issues all of its print requests before unlocking the printer. Before the son accesses the printer, it tries 
to lock it, fails, and is suspended. When the father unlocks the printer, the son locks it and issues 
print requests. 

IDENTIFYING LOCAL RIN OWNERS. LOCRINOWNER identifies at any time the PIN of the process 
that has a particular local RIN locked. This is useful, for example, when father and son processes are 
being synchronized through calls to the ACTIVATE and SUSPEND intrinsics. 

Consider the following example in which a father process acts as a monitor for several son processes. 
The father waits in a suspended state at the top of its loop to be activated by any son. When ac- 
tivated, the father locks a RIN to synchronize its communication with the son. LOCRINOWNER 
determines the PIN of the son that activated the father, since that son will have the WHICHSONRIN 
RIN locked. The father then performs its required duty. The father finally activates the son that ac- 
tivated the father, and the father suspends, releasing the synchronization RIN, and waiting for 
another son to activate it again. An example of Process Synchronization with LOCRINOWNER is: 
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equate whichsonrin = 1, 

synchrin = 2, 
waitforfather= 1 , 
waitforson = 2, 

FATHER PROCESS SON PROCESS 



• 



soncount := 0; 

while soncount <= maxsons do 

begin LOCKLDCRIN Cwhichsonrin) 

SUSPENDCwaitforson, synchrin); LOCKLDCRIN Csynchrin); 
LOCKLDCRIN Csynchrin); ACTIVATE (father); 

owner := LOCRINOWNER Cwhichsonrin); SUSPEND Cwaitforfather, synchrin); 

UNLOCKLOCRIN Cwhichsonrin); 

• » 

• • 
soncount := soncount + 1; 

ACTIVATE Cowner); 
end; 



FREEING LOCAL RINS. To free all local RINs currently reserved for your job, enter: 
FREELOCRIN; 

USER LOGGING 



The MPE User Logging Facility provides a structure for documenting additions and modifications to 
user data bases and subsystem files. Documentation can be recorded on disc, tape., serial disc, and 
cartridge tape. Logging is done programmatically by means of the following intrinsics, which you 
must have User Logging (LG) or System Supervisor (OP) capabilities to use: 

• LOGSTATUS displays status information about currently opened log files. 

• OPENLOG provides access to a logging facility . 

• WR I TELOG writes journal entries to a logging file. This creates a copy of any modifications to a 
data set . 

• CLOSELOG closes access to the logging facility. 

• FLUSHLOG writes the contents of the user logging memory buffer to the disc destination file (disc 
buffer file when logging to a serial device). This intrinsic writes no special records. 

• BEGINLOGposts a special record to the user logging file to mark the beginning of a logical transac- 
tion in the log file. 
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• ENDLOG posts a special record to the user logging file to mark the end of a logical transaction in 
the logging file. When the record is posted, ENDLOG flushes the user logging memory buffer to 
ensure that the record gets to the logging file . 

• LOG INFO obtains information from the logging buffer and passes it to the user. 

If a data set is lost , the user logging file can be used with a copy of the data set file to recover the lost 
transactions. 

How User Logging Works 

When requesting serial files within the logging facility , entries are placed in the buffer area of the 
logging data segment . Once this buffer area is full , the contents are written to the disc buffer file on 
disc. (See Figure 3-10.) If there is no space available in the memory buffer, the result depends upon 
the mode parameter specified : 

• If mode=0 (WAIT) is specified, the process is suspended until the logging process writes the con- 
tents of the memory buffer to disc. Then, the process is reactivated (similar to WAITIO). Space 
becomes available , and your request is moved into the memory buffer . 

• If model (NOW AIT) is specified the communications area of the data segment sends an error 
message indicating the transaction has not been completed . The user needs to resubmit the request 
(similar to NOW AITIO). 

Effective with the G.02.00 release the user can have the system automatically write a changelog 
record and close the user logging file when it becomes full by specifying the auto parameter of the 

:ALTL0Gor :GETL0G command. A new, permanent user logging file is then opened, which has the 
same characteristics as the previous file . It is important to note that user logging files can be changed 
automatically only when the storage media is disc, not tape. To use the auto parameter of the 

:ALTL0G and :GETL0G commands the filename of the existing user log file must end with a three 
digit numeric (e.g. fnameOOl). Then when the new file is constructed the filename digits preceding 
this three digit numeric remain unchanged and the last three digits are incremented by one (i.e. 
fname002). Refer to the MPE V Commands Manual (32033-90006) for additional information on 
the auto parameter of the : ALTL0G and : GETLOG commands . 

The buffer area in L0GBUFF has a maximum capacity of 4K words (32 records). This buffer area 
will be posted, entered, or transferred to the disc buffer file (when logging to a serial device) or the 
disc destination file (when logging to disc) if: 

• A user calls FLUSHL0G, BEGINL0G, ENDLOG, or WRITEL0G in mode=2. (Refer to the 
WRITELOG intrinsic in Section II for information on mode- 2.) 

• There is not enough space in the buffer for another record . 

• The process is interrupted at any time . 

The logging process and logging buffer function differently according to the type of file specified by 
the user. 

When a serial log file is specified , the logging process acts as an interface between the logging buffer 
file and the serial log file by writing records to the serial log file requested. This process is indepen- 
dent of your process. The user can add records to the logging memory buffer at the same time the 
logging process is writing records from the disc buffer to the serial device. As soon as the logging 
process has made space available in the logging buffer file , the user's process will be reactivated . 
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Figure 3-10. User Logging Facility 
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When a disc file is specified, the logging process and logging buffer function differently. Logging 
records are loaded into the buffer area of LDGBUFF (the logging data segment). The records are 
moved to the disc destination file when the buffer area is full. A message is displayed on the Console 
when the destination file becomes full. The process will then stop as soon as the number of users 
equals zero. No other I/Os can access the file. The WRITELOG, BEGINLDG, ENDLOG, and FLUSHLDG 
intrinsics suspend the user process and activate the logging process. If needed, the logging process al- 
locates additional extents (one at a time) to the disc destination file up to the maximum the user 
specified in the : BUILD command. Logging continues until the user-specified maximum is reached 
(same as EOF). Then the logging process reactivates the user process. 

The user needs the record formats to directly access the logging files. 

Logging Record Format : 
record size * 1 2 8 words 
user area =119 words 

LOG RECORD AT OPENLOG: 



11 12 



24 25 



127 



reef 


cksum 


code 


time 


date 


logfd 


log# 


creator 


peb 





LOG RECORD AT WRITELOG: 



127 



rec# 


cksum 


code 


time 


date 


iog# 


Ion 


user area 



LOG RECORD AT CLDSELOG: 



11 12 24 25 



127 



reel 


cksum 


code 


time 


date 


logid 


log# 


creator 


peb 





LOG RECORD AT CHANGELOG: 



2 3 4 6 7 11 12 14 


127 


reel 


cksum 


code 


time 


date 


logld 


eeq 

num 


c-tlm« 


c-dat« 





CRASH MARK: 



127 



reel 


cksum 


code 


time 


date 
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2 3 4 6 7 11 



TRAILER RECORD (STOP): 



2 3 4 6 7 11 



NULL RECORD: 



BEGIN TRANSACTION MARKER: 



6 7 8 9 



END TRANSACTION MARKER: 
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127 



reel 


cksum 


code 


time 


date 


logid 





127 



ree* 


cksum 


code 


time 


date 


logfd 





127 



reel 


cksum 


code 


time 


dote 





127 



reel 


ckeum 


code 


time 


date 


i«g# 


ten 


user area 



127 



feci 


ckeum 


cede 


time 


date 


log* 


ton 


ueer area 



CODE DEFINITION: 

Code ■ 1 Open log record 

2 User/subsystem record 

3 Close log record 

4 Header record 

5 Trailer record 

6 Restart record 

7 Continuation of user or subsystem record 

9 Crash marker 

1 End transaction record 

1 1 Begin transaction record 

12 Change log record (resides in new file; points to old file) 

13 Change log record (resides in old file; points to new file) 
(SPACE) Null record 
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DATA FIELDS OF LOG RECORDS: 

REC# = Double Integer 

CKSUM = Integer 

CODE = Integer 

TIME = Double Integer (from CLOCK intrinsic) 

-DATE = Integer (from CALENDAR intrinsic) 

LDGID = ASCII 

L0G# = Integer 

LEN = Integer 

USERAREA = ASCII 

CREATOR = ASCII 

PCB = Integer 

SEQ NUM = Integer 

C-DATE = Double Integer 

C-TIME = Double 

The code in Word 3 of each logging record identifies the type of record . For example , a " 1 " in the 
second half of the third word indicates an OPENLOG record . 

Privileged users can define a subsystem code in the first half of the logging record code word bits 
(0:8). This code is passed in the index parameter of the OPENLOG intrinsic. 

The checksum (CKSUM) algorithm uses the Exclusive -Or (XOR) function against a base of negative 
one. 

The null record is used as a filler . 

The length field (LEN) contains the number of words in the entire transaction (i.e. the length passed 
to HRITELOG, BEGINLOG, or ENDLOG). If a continuation record is part of the transaction, that record 
will also contain the data length. For example, if a length of 140 (words) is passed to the intrinsic, 
the LEN field will contain 140. Since the user area will only accommodate 119 words the remaining 
21 words will be stored in a continuation record. However, the LEN field of the continuation record 
will indicate the total number of words in the transaction (140 in this example). A positive number 
indicates words; a negative number refers to bytes. 

User Logging Procedures 

To utilize the User Logging Facility, the programmer uses the logging intrinsics in the applications 
program to write data to a logging file to be used for recovery. The user must also write a recovery 
procedure program that can read the log file and apply it to a backup copy of the data set to recover 
data lost in a system failure. User logging does power failure recovery automatically. 

The suggested User Logging procedure includes the following steps : 

1. Select a logging identifier using :GETL0G. If data security is necessary, use passwords/ 
lockwords provided in the :GETL0G command. Specify the configured device class name, i.e. 
DISC, TAPE for magnetic tape, SDISC for serial disc device, and CTAPE for cartridge tape unit 
(such as HP 9140/9144). These must be configured device class names or an F0PEN failure will 
result . 

2. Design the application and data structures. 
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3. Decide what information must be logged in order to recover the data structures of the 
application. The log file will be applied to the backup copy of the data structure to recover data 
lost because of a system failure or power failure. Include the appropriate calls to the User 
Logging intrinsics in your application program to log the data necessary for recovery. 

4. Design and program the recovery procedure. The backup copy of the application data structure 
is necessary to the recovery procedure. The recovery program must recognize the User Logging 
file record formats . 

5. If the logging identifier specified in the :GETLDG command is associated with a disc file, build 
that file with the correct code ( ;C0DE=L0G), and enough disc space to contain one day's output. 
Be generous with the disc file space. Divide the file into several extents; allocate only the first 
extent. This minimizes the impact of a large file on the system. The user logging process allo- 
cates additional extents when necessary (one at a time).* 

6. Have the System Operator start the logging process for your logging identifier. Refer to the 
MPE V Commands Reference Manual (32033-90006) for more information on the :L0G 
command . 

7. If there are changes in the data sets, run your logging application program for the User Logging 
file you specified in the : GETLDG command . 

If it becomes necessary to recover the data sets , restore the backup copy that was saved and run the 
recovery procedure to incorporate any changes made to the data structures. 

Suggested Log File Uses 

Use of a log file starts with your application, especially if many users are accessing the same user log 
file. Set up a log file separate from your data base log file with information which points to your 
entry. The separate log file might include the following information: 

o User, group, and account names you are using in your application. This can be determined by 
using the WHO intrinsic. 

• Job/session input device number, which can also be determined by using the WHO intrinsic. This 
number provides only a history which does not help directly in recovery. 

• Process Identification Number (PIN) of the process accessing the log files. Use the GETPROCID 
intrinsic to obtain the PIN. 

• Date and time of opening the log file. This information can be accessed by the CALENDAR and 
CLOCK intrinsics. (The date and time returned by these intrinsics match the format of this infor- 
mation in the data base log file.) Put in calls to these intrinsics immediately after a successful 
0PENLOG intrinsic call. 

• The fully qualified file name of the data set log file being accessed, including the ASCII code of 
the LOG ID. 

To recover the file listing, read the additional file and open the log file. Search the log file for the 
LDGIDand the creator that match in the 0PENL0G record CODE 1 . Verify it using the date and time. 
Use the PIN to verify the creator in case there are duplicate creators. Then pick up the LOG number. 
All records with this log number will be in your file . 
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This section provides background information on the MPE file system and some typical operations per- 
formed with the MPE file system intrinsics. For more information on the MPE File System, refer to 
the MPE File System Reference Manual (30000-90236). The following operations can be performed 
by using MPE file system intrinsics : 

Open files with F0PEN. 

Parse a file designator and validate that it is syntactically correct with FPARSE. 

Request access and status information about a file with FF I LE I NFQ and FGET I NFO. 

Request file error information with FCHECK. 

Read records (or a portion of a record) from a file with FREADand FREADDIR. 

Write a record (or a portion of a record) to a file with FWRITE and FWRITEDIR. 

Move a specific record from a file into a buffer preparatory to reading the record to the stack 
with FREADSEEK. 

Initiate completion operations for an I/O operation with the I QWA IT intrinsic. 

Read a file label on a labeled magnetic tape file with FREADLABEL. 

Write a file label on a labeled magnetic tape file with FWRITELABEL. 

Obtain information from the file label of a disc file with FLABELINFQ. 

Read a user-defined label from a disc file with FREADLABEL. 

Write a user -defined label onto a disc file with FWRITELABEL. 

Update a record on a disc file with FUPDATE. 

Space forward or backward on a disc or tape file with F SPACE. 

Reset the logical record pointer to any logical record in a fixed -record length disc file with 
FP0INT. 

Perform control operations on a file (or the device on which the file resides) with FCDNTRDL. 

Activate and deactivate access mode options with FSETMQDE. 

Rename an open disc file with FRENAME. 

Determine if an input file and a list file are interactive and/or duplicative with FRELATE. 

Coordinate access to shared files with FLOCK and FUNL0CK intrinsics. 

Close a file with FCL0SE. 
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FILE DEVICE RELATIONSHIPS 

Devices required by files are allocated by MPE. You can specify these devices by class (such as any 
card reader or line printer), or by a logical device number related to a particular device (such as a 
specific line printer). Regardless of what device a particular file resides on, when a user program asks 
to read that file, it references the file by its formal file designator. This is the name that is coded 
into the program, along with the program's specifications for the file. For more information on for- 
mal file designators refer to the MPE File System Reference Manual (30000-90236). Actual subsys- 
tem formal file designators can be found in the MPE V Commands Reference Manual 
(32033-90006). MPE then determines the device on which the file resides, or its disc address if ap- 
plicable, and accesses it for you. When the user program writes information to a particular file to be 
output on a device such as a line printer, again the program refers to the file by its formal file desig- 
nator. MPE then automatically allocates the required device to that file. Throughout its existence, 
every file remains device -independent; that is, it is always referenced by the same formal file desig- 
nator regardless of where it currently resides. 

Non-Sharable Device Access 

Any device which can only handle one set of data at a time is a non-sharable device. The specifica- 
tion of a device by class when a file is opened implies a request for the initial allocation of a previous- 
ly unopened device. The file system, during FDPEN, issues an allocation request to the System 
Operator if necessary. After the Operator answers, F0PEN continues execution. (The device 
specification is ignored when $STDIN, $STDINX, or SSTDLIST is opened.) A job may reallocate an 
opened device by specifying the device's logical device number when the file is opened. In this case, 
no System Operator intervention is required . 

Multiple processes can asynchronously interleave accesses to reallocated devices. Since the file system 
does "anticipatory reads" on buffered input devices, multiple processes should specify Multi -Access 
(MULTI) or Inhibit Buffering (NOBUF) if records must be transmitted in the same order as request- 
ed. In this instance MULTI is preferred. 

File Domains 

The set of all permanent disc files in MPE is known as the system file domain . Within this system file 
domain, files are assigned to accounts and accounts are then organized into groups. You logon using 
an account and group which provides the basis for your local file references. You may be required to 
supply passwords for the account and group to logon , but thereafter (if the default MPE file security 
provisions are in effect) you will have unlimited access to any file within your logon or home group. 
(However, if the file is protected by a lockword, you must know the lock word.) You can also read 
and execute programs residing in any file in the PUB group of your account , and in the PUB . SYS 
group/account . 

Potentially, if the MPE file security provisions at the account, group, and file levels were all 
suspended, and you knew all account and group names and file lockwords, you could access any per- 
manent file in the system once you logon. Note that once you logon, you do not need to know the 
passwords for other accounts and groups to access files assigned to them. You only need to know the 
account and group names. If any of these files are protected by a file lockword, you do need to know 
this lockword . 

For every job or session running in the system , MPE recognizes an accompanying file domain , called 
the "job file domain" or "session file domain". This domain contains all temporary files opened and 
closed within the job or session without being saved (that is, declared as permanent). Files in these 
domains are deleted when the job or session terminates (if they are job/session temporary files), or 
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when the creating program ends (if they are new files, not saved temporary or permanent files when 
closed). 

When a new file is opened it is known only to the program that creates it, and will exist only while 
the program is being executed. At this time, the file name assigned by you need not be unique. But 
if the program tries to save the file as permanent or job temporary (via FCLOSE) , MPE determines 
whether another file with the same name exists in the domain in which you are trying to save thaf 
file (permanent or job temporary). If a name conflict occurs, a CCL condition code is returned to the 
user process from FCLDSE, and the specific error is made available through the FCHECK intrinsic. 
When a program aborts, old files are returned to the domain in which they were found when opened; 
new files are deleted. The fact that a duplicate file name is detected at FCLDSE (not FOPEN) time is 
important for many applications. 



NOTE 



All intrinsics discussed in this section, with the excep- 
tion of FDPEN, FGETINFD, FFILEINFO, FDEVICE- 
CONTROL, and FRENAME, can be called with the DB 
register pointing to a data segment other than the call- 
ing process' stack (split -stack mode). All parameters 
referenced in any calls to these intrinsics are always ac- 
cessed using the current DB -register setting. Privileged 
Mode is required to enter split-stack mode; once in 
split -stack mode, you need not remain in Privileged 
Mode to call file system intrinsics. 

Opening a File 

Before a user process can read, write, or otherwise manipulate a file, the process must initiate access 
to that file by opening it with the FOPEN intrinsic call. This call applies to files on all devices. When 
the FOPEN intrinsic is executed, it returns the file number used to identify the file in subsequent in- 
trinsic calls to the user process. 

If the file is opened successfully (indicated by the CCE condition code), the file number returned is a 
positive integer. If the file cannot be opened (indicated by the CCL condition code), the file number 
returned is zero. Whenever a process is run, MPE calls FOPEN twice to open ISTDIN and ISTDLIST 
for that process before any of the user code is executed. This uses two file numbers. No assumption 
should ever be made concerning the allocation order of these file numbers. 

If a process issues more than one FOPEN call for the same file before it is closed , this results in multi- 
ple, logically separate accesses of tHt file, and MPE returns a unique file number for each such ac- 
cess. Also, MPE maintains a separate logical record pointer (indicating the next sequential record to 
be accessed) for each access where the MULTI -access option was not requested or not permitted at 
FOPEN time. 

In opening a file, FOPEN establishes a communication link between the file and your program by: 
c Determining the device on which the file resides. 

• Allocating the device on which the file resides to your process. If the file resides on a non- 
sharable device, such as magnetic tape, and the user has Non-sharable Device (ND) capability, 
FOPEN determines whether the System Operator must approve allocation of the device , such as an 
unlabeled magnetic tape , or provide a particular media , such as a specific volume for a labeled 
magnetic tape request or special forms for a line printer. If so, FOPEN requests the System 
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Operator to respond appropriately. Disc files generally can be shared concurrently among jobs and 
sessions. Magnetic tape and unit-record devices are generally allocated exclusively to the 
requesting job or session. For example, different processes within the same job may open and have 
concurrent access to a file on the same magnetic tape or unit -record device, if the file has been 
opened with MULTI -access. However, this device cannot be accessed by another job until all ac- 
cessing processes in this job have issued a corresponding FCLDSE call. 

• Verifying your right to access the file under the security provisions existing at the account, group, 
and file levels. 

• Determining that the file has not been allocated exclusively to another process (by the 
EXCLUSIVE option in an FOPENcall issued by that process). 

• Processing user labels (for files on disc). For new files on disc, FDPEN specifies the number of user 
labels to be written. 

• Allocating to the file the number of extents initially requested (for new disc files). 

• Constructing the control blocks required by MPE for this particular access of the file. The infor- 
mation in these blocks is derived by merging specifications from five sources, listed below in des- 
cending order of precedence : 

1 . The file label , obtainable only if the file is an old file on disc. This information overrides in- 
formation from any other source. Label formats are presented in the MPE File System 
Reference Manual (30000-90236). 

2. FDPEN overrides of incompatible options. 

3. The parameter list of a previous :FILE command referencing the same formal file designator 
named in this F0PEN call, if such a command was issued in this job or session. This is only 
true, if file equations were not disallowed. 

4. The parameter list of this F0PEN intrinsic call. 

5. System default values provided by MPE (when values are not obtainable from the above 
sources). 

When information from one of these five sources conflicts with that from another, pre-empting 
takes place according to the order of precedence shown above. To determine the specifications ac- 
tually taking effect, the user can call the FGETINF0/FFILEINF0 intrinsics, described later in this 
section. (Notice that certain sources do not always apply or convey all types of information. For 
example, no file label exists when a new file is opened, and so all information must come from the 
last four sources above . ) 

Files on Non-Sharable Devices 

When a process opens a disc file, the FDPEN call will specify whether the file is an old or new file; an 
old file is an existing file, and a new file implies that the file is to be created. When a process accesses 
a file that resides on a non-sharable device, the device's attributes may override your old/new 
specification . Specifically , devices used for input only , such as card readers , automatically imply old 
files. Devices used for output only, such as line printers, automatically imply new files. Serial in- 
put/output devices, such as terminals and magnetic tape units, follow the old/new specification in 
your FDPEN call. 
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When a job attempts to open an old file on a non-sharable device, MPE searches for the file in the 
Input Device Directory (IDD). If the file is not found, a message is transmitted to the System Console 
requesting the Operator to locate the file by taking one of the following steps: 

1. Indicate that the file resides on a device that is not in auto-recognition mode. No :DATA com- 
mand is required ; the Operator simply allocates the device. 

2. Make the file available on an auto -recognizing device, and allocate that device. 

3. Indicate that the file does not exist on any device; the user's FDPEN request will be rejected. 

When a job opens a new file on a non-sharable device (other than magnetic tape), the Operator is not 
required to intervene. In these cases, the first available device is used. (A non-sharable device is 
considered directly available if it is not being used , or if it is being used by the requesting job and is 
requested by its logical device number.) 

The specification of a device class when FDPEN is issued implies a request for the initial allocation of a 
previously unopened device. (The device parameter is ignored when $STDIN, $STDINX, and 
$STDLIST are opened.) A job may reallocate an opened device by specifying the device's logical 
device number when the file is opened. The FGETINFO/FFILEINFD intrinsic should be used to 
determine the logical device number assigned to an opened file. The subsequent FOPEN which supplies 
this logical device number should insure that no existing file equation overriding the device number is 
accidentally picked up. 

When a job opens a new file on a magnetic tape unit, Operator intervention is usually required. The 
Operator must make the tape available, unless the tape is already mounted and recognized by MPE, it 
is auto -allocating, or the device is being reopened by the same or related process. 



HOW TO USE FILES 



The remainder of this section explains what you can accomplish with files using the file system intrin- 
sics. An attempt is made to show practical applications for the intrinsics, instead of merely restating 
the purpose of each intrinsic as discussed in Section II. 

Internal Operations for File Accessing 

Before a file can be used, it must be opened with the FOPEN intrinsic. If you are programming in 
SPL, you must call the FDPEN intrinsic directly from your program. The compilers for other lan- 
guages, such as FORTRAN and COBOL, emit code which calls FDPEN and opens the file for you. In 
any case, however, whether called explicitly by your program, or called for you by the language's 
compiler, the FDPEN intrinsic is used to open all files in a program. Several items which should be 
considered before using FDPEN are discussed in the following paragraphs. 

For example, consider what occurs when a user coding a program in SPL performs a call to the FOPEN 
intrinsic to open a new disc file. (A new disc file is a file that has not existed previously in the sys- 
tem.) One of the fundamental things that occurs at FOPEN time is that an access interface is created 
for the file. This access interface comprises a number of control blocks that are created, and which 
contain information about the file . In addition , if the new disc file is opened with buffered access , a 
buffer space is allocated in the Access Control Block (ACB) to contain the number of records per 
block that the user has specified in the FDPEN call. The buffer space is large enough to hold a block 
of information to be sent to the disc . 
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The control blocks are pointed to by an entry in the user's stack. This entry is called an Available File 
Table (AFT), and is part of the Process Control Block Extension (PCBX) in the user's stack. The next 
thing that occurs is that file space is allocated to the file . On each system disc or private volume disc 
there is a table of free space managed by MPE. The file system refers to the file space table and allo- 
cates initial space for this file (the number of sectors allocated depends on the parameters specified in 
the FDPEN call) by deallocating free space from the table and writing a file label in the first sector of 
the newly allocated space. Upon the successful completion of an FDPEN call, an integer value is 
returned to the calling program as the file number. This integer value is an index into the AFT, and 
the appropriate AFT entry in turn then points to the control block that belongs to this particular file. 

Figure 4-1 shows the stack and the AFT entry pointing to the control block. The control block con- 
tains buffers, in this case, enough room for three logical records. In the example shown in Figure 
4- 1 , each record is 80 bytes and the records are grouped into a block of three. 

A partial list of items contained in a disc file label is shown below ; once their values are established , 
they cannot be changed by subsequent FOPEN operations : 

• File name. 

• Sector address. 
Maximum number of logical records. 
Logical record size. 

• Block size. 

• Foptions (exception: disallow file equations and domain bits). 

• Number of extents . 

• Extent size. 

• File code . 

The linkage, then, goes from the user's stack, via the AFT, to the control block; from the control 
block there is a pointer to the label on the disc itself. In the simplified example of Figure 4-1 the file 
label is shown on the system disc. However, it could be on any disc in the system. 

Since this is a new file, there is no information in the file. Therefore, the access mechanism is the 
only information the system has for this file. Depending on the FOPEN parameters specified, it is pos- 
sible to write on this file . 

If the FWR I TE intrinsic was called to write a single 80-byte record, that record would be moved from 
the user's stack to position number 1 in the buffer. As soon as that physical move from the stack to 
the buffer is complete, the FWRITE is also complete as far as the program is concerned. However, no 
actual write to the disc takes place. An FNRITE call to write record number 2 would consist of a 
similar move from the stack position number 2 in the buffer. Subsequently, record number 3 would 
occupy position 3 in the buffer . Immediately after the buffer becomes full , when the third record 
has been moved to the buffer, the entire block of information is then transferred to the disc. Thus, 
when a file is accessed in a buffered manner, records actually are moved from the stack to the buffer. 
Then , when the last record in a block has been moved to the buffer , a physical write of a complete 
block occurs. That is, a whole block (in this case three records) is transferred to the system disc. 
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At FCLOSE time, the access interface is dismantled. If the file is a new file, you must now decide 
whether you want the file to remain in the system as a permanent file, as a job/session temporary 
file, or whether you want the file to be deleted from the system. Therefore, if information about the 
file is to be saved in the system , the FCLDSE intrinsic is used to close the file with a permanent dis- 
position. The name of the file, which is available to the file system in the Access Control Block 
(ACB), is posted in the system directory along with your logon account and the group you have 
specified. MPE finds that area of the directory and posts an entry in the system directory for that file 
name. If the name is FILE1 , then FILE1 resides on the disc at a certain sector address. Referring to 
Figure 4- 1 , you can see that in the system directory there will be an entry that includes the file name 
and some sector address, for example, %123. The sector address %1 23 then points to the first extent 
which includes the label. 
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Figure 4- 1 . File Access Interface for New Disc Files 
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As soon as the name of the file, pointer to the file label, and accounting information such as creation 
date, have been entered in the system directory the file access interface is dismantled. The control 
blocks and buffers are deleted from the system and the entry in your stack in the Available File Table 
(AFT) is removed. 

When the FCLOSE operation is complete, the disc file becomes a permanent file in the system. It can 
now be opened as an old disc file. If a file with the name of FILE1 already exists in your logon ac- 
count and specified group, this will not be noticed until FCLDSE is called, and, at that time, results in 
an error. 

Figure 4-2 shows that now there is an entry in the system directory with a file name of FILE1 and a 
sector address of % 123. To open this file as an existing or old file, the FDPEN parameters would have 
to be changed to specify an old file. The resulting operation would be similar to the previous example 
with one exception: since an existing file is being opened, it is not necessary to allocate disc space for 
it. It is necessary for the system to establish a mechanism for the user to access the disc file. In other 
words, the system makes an entry in the Available File Table (AFT), creates a new Access Control 
Block (ACB) and File Control Block (FCB), pointing to the existing file on the disc. 
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Figure 4-2. Directory File Name and Label Address Pointer 

Figure 4-3 shows what occurs if an FOPEN call is issued for an old file named FILE1. In this case, 
FOPEN specifies an old file and must supply the name of this file ; MPE searches the system directory 
under the appropriate account and group for this file. 
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Once the file is found, MPE establishes the access mechanism, consisting of an ACB and FCB as 
before, and a map from the FCB of the extent address on disc. 

The other type of old file is the job or session temporary file. One of the differences between a job/ 
session temporary file and a permanent file is where the actual entry is placed when the file is closed. 
Each job or session has a table called the Job Temporary File Directory. In the case of a file that is 
saved with temporary disposition , the name of the file and a pointer to the file label are stored in this 
Job Temporary File Directory. (Note that the Job Temporary File Directory is unique to each job or 
session.) Another difference between a job temporary file and a permanent file is that when a job/ses- 
sion terminates, all job/session temporary files are deleted from the system, and file space that was 
held by such files is returned to the system . 
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Figure 4-3. File Access Interface for Old Disc Files 

File characteristics are obtained from different sources , depending on whether the file is a new disc 
file , an old disc file , or a file on a device other than disc. 

For a new disc file, created with FOPEN joptions bits (14:2)=00, the characteristics are obtained from 
FOPEN intrinsic call parameters and defaults. These characteristics may be overridden by :FILE 
command parameters. The disc file and the file label are created according to the characteristics 
specified above. (This label remains with the file during its entire existence on the system.) 
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Old permanent disc files are opened with FOPEN f options bits (14: 2)=01 . Old temporary disc files are 
opened with FOPEN f options bits (14:2)=10. In either case the file characteristics are obtained from 
the disc file label, FOPEN intrinsic parameters and default conditions. Some of these characteristics 
may be overridden by :FILE command parameters. The disc file label may override either of the 
above specifications. If foption bits (14:2)=1 1 the existing file can be either an old temporary or an 
old permanent file with the Job Temporary File Directory searched first . 

When a file is opened on a device other than disc, the file characteristics are established by FOPEN 
intrinsic call parameters and defaults. Any :FILE command parameters will override these specifica- 
tions and defaults. However, any device -dependent restraints imposed by the file system will over- 
ride both of the above settings . 

If you have the Non-Sharable Device (ND) capability, the file system allows you to open a physical 
I/O device in the same manner as you would open a disc file. (Discs are the only devices which are 
considered by MPE to be sharable among several users.) When a non-sharable device has been opened 
by FOPEN, it is referred to as a devicefile. The physical characteristics of each different device avail- 
able to the file system can differ substantially and these differences affect the characteristics which 
are permitted for corresponding devicefiles. For this reason, the file system imposes a number of 
device -dependent restrictions on devicefiles. Card reader files, for example, are required to have 
read-only access with a blocking factor of one. A summary of these restrictions is presented in Table 
4-1. 

It should also be noted that some non-sharable devices can be spooled by MPE. This means that data 
input from and output to such devices is stored temporarily on the disc in transit between the physical 
devices and the user program. Because data can be temporarily buffered in a disc file, the program 
assumes that all physical device files which it requires are constantly available to it. Input data typi- 
cally is read and stored before a program requires it, and output data is delayed until the program's 
file operations are complete (at FCLOSE time). Other than these external variations, most differences 
between a spooled and a non-spooled devicefile are insignificant to the program. 

One exception is applications which write large reports. Because a spoolfile is a disc file, it has a max- 
imum size of 32 extents, each of which is of a fixed configured size. This size may be too small and 
therefore, all extents may become filled before the job is finished. As a result, data may be lost. The 
solution is to have the System Manager raise the number of sectors per spoolfile extent. 

The System Manager reconfigures the extent size in the INITIAL/SYSDUMP dialog. The appropriate 
question is "# OF SECTORS PER SPOOLFILE EXTENT". A configured extent size of 384 sectors 
means the spoolfile has room for approximately 25,000 lines. 

An alternative to generating one large output spoolfile is to periodically close the output file and open 
a new one. A large report program might start a new output file every 200 pages. While this tech- 
nique requires gathering several files for the complete report, it has the advantage of allowing the 
first portion of the report to print while the rest of the program is still running. 

When a non-sharable devicefile is opened, the device has to be allocated by the system so that the 
calling process can access the file. MPE classifies devices as "NEW or OLD", "OLD only" , or "NEW 
only", depending on the device type. Table 4-2 shows the manner in which devices are classified. 
Included in Table 4-2 is the device name, its device type (in octal), and whether it is considered to be 
OLD/NEW, OLD only, or NEW only. If FOPEN specified a device type that is considered by MPE to 
be output only, MPE considers this to be a NEW file. Normally, NEW files do not require special at- 
tention. If the device is available, it will be allocated to the user. Printer forms message, plotter, or 
magnetic tape requests are the exceptions, however, and require Operator intervention. 
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Table 4- 1 . Device -Dependent Restrictions 



INPUT ONLY DEVICES (SERIAL) 

Card Reader/Paper Tape Reader 
No carriage control 
Undefined-length records 
If card reader, ASCII only (can only read ASCII cards without using 

FCONTROL) 
Blocking factor = 1 
Domain = 1 (OLD permanent) 
If not ASCII, then NOBUF 

If FOPEN aoptions access type = 1,2,3, then FOPEN fails (access 
violation) 



INPUT/OUTPUT DEVICES (PARALLEL) 

Terminals 
ASCII 
NOBUF 

Undefined-length records 
Blocking factor = 1 



INPUT/OUTPUT DEVICES (SERIAL) 

Magnetic Tape Drive/Serial Disc Drive/Card Reader/Punch 
No restriction 



OUTPUT ONLY (SERIAL) 

Line Printer/Card Punch/Paper Tape Punch/Plotter 
If Line Printer, ASCII only 
Undefined-length records 
Blocking factor = 1 
Domain = NEW 

Access type = 1, write only (if read only specified, access 
violation results) 



UNDEFINED (COMMON CHECKING) 

If carriage control specified and not ASCII, access violation results 
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Table 4-2. Classification of Devices 



DEVICE NAME 


DEVICE TYPE 
NUMBER (OCTAL) 


CLASSIFICATION 


Moving-Head Disc 


00 


NEW or OLD 


Flexible Disc 


02 


NEW or OLD 


7911, 7912, 7914, 7933, or 7911/ 
7912 Integrated Cartridge Tape Unit 
and 7945 Disc, and 9144 Cartridge 
Tape Unit. 


03 


NEW or OLD 


Card Reader 


10 


OLD only 


Paper Tape Reader 


11 


OLD only 


Terminals, DSN/DS pseudo terminals, 
NS/3000 pseudo devices, multipoint 
terminals, multipoint supervisor, 
asynchronous terminal controller. 


20 


NEW or OLD 


Intelligent Network Processor 
(INP) 


21 


NEW or OLD 


Printing Reader Punch 


24 


NEW or OLD 


DSN/MRJE Pseudo Device 


26 


NEW or OLD 


Magnetic Tape Drive 


30 


NEW or OLD 


Line Printer 


40 


NEW only 


Card Punch 


41 


NEW only 


Plotter 


43,44,45 


NEW only 



The flowchart shown in Figure 4-4 illustrates how MPE allocates a non-sharable device when an 
F0PEN request is received. First, MPE considers the device type requested by the FOPEN call. If the 
device type is input only, this is considered to be an OLD file. Because MPE considers the file to be 
an OLD file, it searches for a predefined input file, for example, a file identified with the :DATA 
command. If no such file is found, MPE sends a message to the System Operator asking for the logical 
device number of the input device. 

If an input/output type of device is specified , MPE next considers the user access requested in the 
FOPEN call. If read only was requested, the file is considered to be an OLD file. If write only, MPE 
considers the file to be a NEW file. 

If the FOPEN call requests a user access of input/output , or any other mode (except read only or write 
only), MPE next looks at the type of file domain specified in the call (NEW or OLD) and opens the 
file accordingly. The system device directories contain entries for each device that contains a file. 
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Figure 4-4. Device Allocation Flowchart 
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Non -spooled devices can have only one file (for example , a card deck in the read hopper of a card 
reader), but spooled devices can have several file entries (for example, card decks which have been 
read in by the device and are stored as spoolfiles on disc to await access). Such devicefiles are iden- 
tified by :DATA commands. Information from a :DATA command image is used to build the device 
directory entry and identifies the file by user name and account name and (optionally) job name 
and/or file name. The data file may be accessed by a user program when its request matches the 
:DATA information and the file is in the READY state. In the case of an unspooled card reader, this 
means that only the : DATA card has been read in , and the rest of the deck awaits processing . In the 
case of a spooled card reader, however, this means that the :DATA card and the entire deck have been 
read and await processing in the form of a disc spoolf ile . A permanent : DATA file can be created on 
disc. This file can be made available to user programs by using the : STREAM command. This also 
results in a disc spoolfile. Refer to the MPE V Commands Reference Manual (32033-90006) for ad- 
ditional information of the : STREAM command . 

If the entry in the device directory indicates that the device is opened, a user process has already 
opened the devicefile (device or spoolfile) successfully. In this case, access to the same non-sharable 
device is granted only if the requesting process is in the same process tree as the process which has the 
file open. This is accomplished by referencing a logical device number, not a device class name. 
These subsequent calls to FOPEN will not require Operator intervention; the first device allocation 
request is the only one issued to the Operator. This technique might be used by a program which does 
a great deal of magnetic tape processing but wants to avoid multiple tape allocation messages. 
Attempts to use this technique with a printer can result in intermixing of output data . 

A condition code error is returned to the calling process if : 

• The device type specified an input-only device and the requested access was write only. 

• The device type specified an output -only device and the requested access was read only. 
A message to the Operator will be printed if: 

• The device is a card reader (spooled or unspooled) and a predefined file with a :DATA card) can- 
not be located to match the file requested. 

• The device is a line printer and uses the forms message option. If the line printer is spooled, the 
Operator dialog takes place when the file is printed, not when it is created by the user program. 

• The device is a magnetic tape device and automatic allocation, described below, is not used. 

• The device is a plotter. 

The Operator message is omitted if: 

• The device is being reopened by logical device number by a process in the same process tree as the 
one which originally opened the device (except that forms message requests always result in an 
Operator message). 
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• For magnetic tapes and serial discs only : 



1. The call to FOPEN specifies an ANSI or IBM labeled tape or serial disc, and media with a 
valid matching label has already been mounted and recognized by 

2. The FDPEN request properly specifies a magnetic tape or serial disc device which has been 
configured for automatic allocation , and which is available (not assigned to another process 
tree) . Refer to the MPE V System Operation and Resource Management Reference Manual 
(32033-90005) for a description of the requirements for automatic allocation of magnetic 
tapes. 

Parsing and Validating File Designators 

The FPARSE intrinsic parses and validates a file designator string to determine if it is syntactically 
correct. You can employ this intrinsic to check a formal designator representing a file before at- 
tempting to open the file via FOPEN. FDPEN also calls FPARSE, however, by calling FPARSE directly 
through your program , syntax errors are easier to identify . 

MPE file designators used for the file system and two user interface commands include a remote en- 
vironment ID {envid). This allows the user to indicate that a file is to be accessed from a remote en- 
vironment established by the user with the :DSLINE or : REMOTE HELLO command. FPARSE 
facilitates the changes required for the file designator extension. It provides the only location within 
MPE where file designators are parsed and syntax is checked. 

The optional items (input) and vectors (output) arrays enable you to acquire parsing information for 
the file designator; namely the length of each item and its position in the string. The items array 
must be set up before the call to FPARSE. This is done by entering the item numbers for which pars- 
ing information is required into the items array. They may be entered in any order you desire. The 
items array is terminated with a zero entry. The possible items (itemnums), as shown in the examples 
below, are file name (1), lockword (2), group name (3), account name (4), and environment ID (5). 
The environment ID is treated as a single item and is not parsed into environment name , domain , and 
organization . 

The following are examples of the items and the vectors array pair. The order of entries in the vec- 
tors array corresponds to the order of items in the items array. Each double word entry in the vectors 
array will return the byte offset of the item in the first word , and the length in bytes of the item in 
the second word. However, the last entry of the vectors array has a different meaning from that of 
the other entries: The second word gives the total length of the file string, and the first word gives a 
system file code when applicable. 
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EXAMPLE 1 : 

In Example 1 the file string is "FILENAME/LOCKWORD. GROUP. ACCOUNT: ANIMAL. I NDDCL . HPBCG" : 

1111111111 22222222223333333333444444444455 
01 2345678901 2345678901 2345678901 2345678901 2345678901 
"filename/lockword. group. account :animal . inddcl . hpbcg " 



items array 

111111 
0123456789012345 

+ + 

: 1 

i__ 

: 5 

• 

• 

! 3 

! 

! 4 

■ 

: 2 

!_____ 

I ——— — — 





vectors array 

1111111111222222222233 

01 2345678901 2345678901 2345678901 

+ + 



■ 
+- 



ic o): 





■ 

■ 


8 


i 

!C 1)' 


32 


! 


19 


IC 2) 
IC 3) 
IC 4) 


18 


■ 
i 


5 


24 


! 


7 


9 


■ 
■ 


8 


■ 

IC 5) 


: 


! 


51 



The items array, as illustrated above, can be listed in any order, or left unspecified if not 
required. 



EXAMPLE 2: 

In Example 2 the file string is "*FILENAME:ANIMAL": 

111111 
0123456789012345 
"*filename:animal " 



items array 

111111 

0123456789012345 

+ + 

1 



vectors array 

1111111111 222222222233 

01 2345678901 2345678901 2345678901 

+ + 



2 

3 
4 
5 




!C 0)i 

IC 1) 


1 


! 


8 





! 





IC 2) 





! 





!C 3) 
IC 4) 
iC 5) 





1 





10 


1 


6 


i 


! 


15 
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EXAMPLE 3: 

In Example 3 the file string is " $OLDPASS" : 

012345678 
"$DLDPASS " 



items array 

111111 
0123456789012345 

+ + 

1 



2 
3 
4 
5 




vectors array 

1111111111 222222222233 
01 2345678901 2345678901 2345678901 

+ + 

« n • a j 

: 



( 2)! 

■ 

C 3)! 



C 4)! 

\ 

C 5Di 






! 


8 


































3 




8 



Note that " $" is a special exception to the rules of file names and is considered part of the file name 
unlike " *" , which is not. 

Opening a New Disc File 

Figure 4-5 contains an SPL program which opens two files: a card reader file and a new disc file. 
The second FOPEN call in Figure 4-5 (Statement 00019000): 

QUT:=FOPENCDUTPUT,%4,%101 ,128); 
opens the new disc file. The parameters specified are : 

fonraldesignator DATAONE, which is contained in the byte array OUTPUT. 

f options %4, for which the bit pattern is as follows: 

r— i i -i i b(ts 

BINARY 
OCTAL 

The above bit pattern specifies the following file options : 

Domain: New file. Bits (14:2) = 00. 
ASCII/Binary : ASCII . Bit ( 1 3 : 1 ) = 1 . 
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aoptions 



X1 01 , for which the bit pattern is as follows: 
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11 


12 
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14 
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1 

















1 


















1 













1 





BITS 

BINARY 

OCTAL 



The above bit pattern specifies the following access options : 

Access Type: WRITE access only. Bits (12:4)= 0001. 
Exclusive: EXCLUSIVE access. Bits (8:2) = 01 . 

recsize The logical record size is specified as 1 28 words. 

All other parameters are omitted from the FDPEN intrinsic call. 

Once the file is opened, the file number (used by other system intrinsics when referencing this file) is 
returned to the variable OUT. 

The condition code for second F0PEN call is checked with the statement on line 00020000 of Figure 
4-5. If the condition code is CCL, signifying that the FDPEN request was denied, the next four 
statements, starting with the BEG IN statement, are executed. 

The statement on line 00036000 of Figure 4-5 calls the PRINT 'FILE'INFD intrinsic, which prints a 
File Information Display on the standard list device, enabling you to determine the error number 
returned by F0PEN. The parameter (OUT) specifies the file number returned through the FDPEN in- 
trinsic. If the file was not opened successfully, OUT is set to 0, where specifies that the File 
Information Display will reflect the status of the file referenced in the last call to F0PEN. Refer to 
Appendix A for a discussion of the File Information Display. 

The QUIT intrinsic call (statement 00023000 in Figure 4-5) aborts the process. The parameter (2) is 
an arbitrary user-supplied number. When a QUIT intrinsic is executed, this number is printed as part 
of the resulting abort message, allowing you to determine, in the case of multiple QUIT intrinsic calls 
in a program, which specific QUIT call was executed. 



NOTE 



The QUIT intrinsic causes MPE to close all files with no 
change. Thus, new files are deleted, and old files are 
saved and assigned to the same domain to which they 
belonged previously. This may be overridden by a 
: FILE command. 
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PAGE 0001 HP32100A.08.01 [4W] (C) HEWLETT-PACKARD COMPANY 1980 


00001000 


00000 





$C0NTROL USLINIT 




00002000 


00000 





BEGIN 




00003000 


00000 


1 


BYTE ARRAY INPUT(0 : 6 ) : ="INFILE " ; 




00004000 


00005 


1 


BYTE ARRAY DEV(0 : 4) : ="CARD "; 




00005000 


00004 


1 


BYTE ARRAY 0UTPUT(0 : 7) : ="DATAONE "; 




00006000 


00005 


1 


ARRAY BUFFER(0:127) ; 




00007000 


00005 


1 


INTEGER IN.OUT.LGTH; 




00008000 


00005 


1 








00009000 


00005 


1 


INTRINSIC FOPEN,FREAD,FWRITE,FCLOSE 


,PRINT'FILE'INFO,QUIT; 


00010000 


00005 


1 








00011000 


00005 


1 


<< 


END OF DECLARATIONS >> 




00012000 


00005 


1 




IN:=F0PEN(INPUT,%5, ,40,DEV) ; 


<<CARD READER>> 


00013000 


00012 


1 




IF < THEN 


<<CHECK FOR ERROR>> 


00014000 


00013 


1 




BEGIN 




00015000 


00013 


2 




PRINT'FILE'INFO(IN) ; 


<<PRINT ERR0R>> 


00016000 


00015 


2 




QUIT(l) ; 


<<ABORT>> 


00017000 


00017 


2 




END; 




00019000 


00017 


1 




OUT : =FOPEN( OUTPUT, %4,%10 1,128) ; 


<<NEW DISC FILE>> 


00020000 


00030 


1 




IF < THEN 


<<CHECK FOR ERROR>> 


00021000 


00031 


1 




BEGIN 




00022000 


00031 


2 




PRINT'FILE'INFO(OUT) ; 


<<PRINT ERR0R>> 


00023000 


00033 


2 




QUIT(2); 


<<ABORT>> 


00024000 


00035 


2 




END; 




00025000 


00035 


1 


COPY'LOOP: 




00026000 


00035 


1 




LGTH:=FREAD(IN, BUFFER, 40) ; 


<<READ A CARD>> 


00027000 


00043 


1 




IF < THEN 


<<CHECK FOR ERROR>> 


00028000 


00044 


1 




BEGIN 




00029000 


00044 


2 




PRINT'FILE'INFO(IN); 


<<PRINT ERROR>> 


00030000 


00046 


2 




QUIT(3); 


<<AB0RT>> 


00031000 


00050 


2 




END; 




00032000 


O0050 


1 




IF > THEN GO END 'OF 'FILE; 


<<CHECK FOR E0F>> 


00033000 


00051 


1 




FWRITE( OUT, BUFFER, LGTH.O) ; 


<<C0PY CARD TO DISC>> 


00034000 


00056 


1 




IF <> THEN 


<<CHECK FOR ERR0R>> 


00035000 


00057 


1 




BEGIN 




00036000 


00057 


2 




PRINT'FILE'INFO(OUT) ; 


<<PRINT ERR0R>> 


00037000 


00061 


2 




QUIT(4); 


<<ABORT>> 


00038000 


00063 


2 




END; 




00039000 


00063 


1 




GO COPY'LOOP; 


<<CONTINUE COPYING>> 


00040000 


00066 


1 


END 


OF'FILE: 




00041000 


00066 


2 




FCLOSE(OUT,%1,0) ; 


<<MAKE PERMANENT>> 


00042000 


00072 


1 




IF < THEN 


<<CHECK FOR ERROR>> 


00043000 


00073 


1 




BEGIN 




00044000 


00073 


2 




PRINT'FILE'INFO(OUT) ; 


<<PRINT ERR0R>> 


00045000 


00075 


2 




QUIT(5); 


<<ABORT>> 


00046000 


00077 


2 




END; 




00047000 


00077 


1 


END 







Figure 4-5. Opening a New Disc File 
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Opening an Old Disc File 

Figure 4-6 contains an SPL program that opens three files: an old disc file, $STDIN, and SSTDLIST. 
Statement 00016000: 

DFILE1 :=F0PEN(DATA1 ,%5,%345,128); 
opens the old disc file. The parameters specified are: 

formaldesignator DATADNE, which is contained in the byte array DATA1 . 

f options %5, for which the bit pattern is as follows : 

r i r i i I 0(Ts 

BINARY 
OCTAL 

The above bit pattern specifies the following file options : 

Domain: Old permanent file. The system file directory should be 
searched . Bits ( 1 4 : 2) = 1 . 
ASCII/Binary: ASCII. Bit (13:1)= 1 
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aoptions 



%345, for which the bit pattern is as follows: 
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recsxze 



BITS 

BINARY 

OCTAL 



The above bit pattern specifies the following access options : 

Access Type: Update access. (This file is updated later in the program with 
the FUPDATE intrinsic.) Bits (12:4) - 0101. 
Multirecord: Non-multirecord mode. Bit (11:1) = . 
Dynamic Locking: Dynamic locking allowed. Bit (10:1)= 1 . 
Exclusive: Share access. Bits (8:2) = 11. 

The logical record size is specified as 1 28 words. 



All other parameters are omitted in the F0PEN intrinsic call. Note that for existing files F0PEN will 
return a lockword violation (FSERR92 via FCHECK) if the file has a lock word, and the lockword is not 
included in the formaldesignator parameter nor (for sessions only) supplied by the user on request. 

Once the file is opened, the file number (used by other file system intrinsics when referencing this 
file) is returned to the variable DFILE1 . 



4-20 



Accessing and Altering Files 



PAGE 0001 


HP32100A 


00001000 


00000 





00002000 


00000 





00003000 


00000 


1 


00004000 


00005 


1 


00005000 


00005 


1 


00006000 


00005 


1 


00007000 


00005 


1 


00008000 


00005 


1 


00009000 


00000 


1 


00010000 


00000 


1 


00011000 


00000 


1 


00012000 


00000 


2 


00013000 


00002 


2 


00014000 


00004 


2 


00015000 


00000 


1 


00016000 


00000 


1 


00017000 


00011 


1 


00018000 


00015 


1 


00019000 


00024 


1 


00020000 


00030 


1 


00021000 


00040 


1 


00022000 


00044 


1 


00023000 


00044 


1 


00024000 


00044 


1 


00025000 


00047 


1 


00026000 


00053 


1 


00027000 


00061 


1 


00028000 


00065 


1 


00029000 


00070 


1 


00030000 


00075 


1 


00031000 


00101 


1 


00032000 


00110 


1 


00033000 


00114 


1 


00034000 


00115 


1 


00035000 


00121 


1 


00036000 


00125 


1 


00037000 


00127 


1 


00038000 


00133 


1 


00039000 


00140 


1 


00040000 


00140 


1 


00041000 


00142 


1 


00042000 


00146 


1 


00043000 


0O151 


1 


00044000 


00155 


1 



08.01 [4W] (C) HEWLETT-PACKARD COMPANY 1980 

SCONTROL USLINIT 

BEGIN 

BYTE ARRAY DATA1 (0 :7) : ="DATAONE "; 

ARRAY BUFFER(0:127) ; 

INTEGER DFILE 1 , LGTH .DUMMY , IN , LIST ; 

INTRINSIC FOPEN , FREAD , FUPDATE , FLOCK , FUNLOCK , FCLOSE , 

PRINT 'FILE 'INFO, QUIT, FWRITE , FREAD ; 
PROCEDURE FILERROR(FILENO,QUITNO) ; 
VALUE QUITNO; 
INTEGER FILENO, QUITNO; 
BEGIN 

PRINT'FILE'INFOfFILENO) ; 
QUIT(QUITNO) ; 
END; 
<<END OF DECLARATIONS) > 

DFILE1:=F0PEN(DATA1,%5,%345,128); <<OLD DISC FILE>> 

IF < THEN FILERR0R(DFILE1,1); <<CHECK FOR ERROR>> 

IN:=FOPEN( ,%244); 

IF < THEN FILERROR(IN,2); 

LIST:=F0PEN(,%614,%1) ; 

IF < THEN FILERROR(LIST,3) ; 



<<$STDIN>> 
<<CHECK FOR ERROR>> 
<<$STDLIST>> 
<<CHECK FOR ERROR>> 



UPDATE 'LOOP: 

FLOCK(DFILEl.l) ; 

IF < THEN FILERR0R(DFILE1,4); 

LGTH:=FREAD(DFILE, BUFFER, 128) ; 

IF < THEN FILERR0R(DFILE1,5) ; 

IF > THEN GO END'OF'FILE; 

FWRITE(LIST, BUFFER. -20, %320) ; 

IF <> THEN FILERR0R(LIST,6); 

DUMMY :=FREAD( IN, BUFFER (30), 5) ; 

IF < THEN FILERR0R(IN,7); 

IF > THEN GO END'OF'FILE; 

FUPDATE(DFILE1, BUFFER, 128) ; 

IF <> THEN FILERR0R(DFILE1,8) ; 

FUNLOCK(DFILEl) ; 

IF <> THEN FILERR0R(DFILE1,9) ; 

GO UPDATE 'LOOP; 
END'OF'FILE; 

FUNLOCK(DFILEl) ; 

IF <> THEN FILERROR(DFILEl.lO); 

FCLOSE(DFILE1,0,0); 

IF < THEN FILERROR(DFILEl.ll) ; 
END. 



<<LOCK FILE/SUSPEND 
<<CHECK FOR ERROR>> 
<<GET EMPLOYEE RECO 
<<CHECK FOR ERROR>> 
<<CHECK FOR EOF>> 
<<EMPLOYEE NAME>> 
<<CHECK FOR ERROR>> 
<<EMPLOYEE NUMBER >> 
<<CHECK FOR ERROR>> 

<<EMPLOYEE REC0RD> > 
<<CHECK FOR ERROR>> 
<<ALLOW OTHER ACCES 
<<CHECK FOR ERROR>> 
<<CONTINUE UPDATE>> 

<<ALLOW OTHER ACCES 
<<CHECK FOR ERROR>> 
<<DISP-NO CHANGE> > 
<<CHECK FOR ERROR>> 



Figure 4-6. Opening an Old Disc File 
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The condition code for this FOPEN is checked in line 00017000 of Figure 4-6. If the condition code 
is CCL, the error-check procedure FILERRDR is called, and two parameters, DFILE1 and 1, are 
passed to it for FILENDand OUITNO. (Refer to statements 00008000 through 00014000 in Figure 
4-6.) DFILE1 contains the file number (assigned to it when the FOPEN intrinsic opened the file) to be 
passed by FILEN0, and 1 represents an arbitrary user-supplied number to be passed by QUITND. 

The FILERROR procedure passes the file number (through F I LEND) to the PRINT 'FILE 'INFO intrin- 
sic. If the file was not opened successfully, FILENO is set to , where specifies t status of the file 
referenced in the last call to FOPEN. The PR I NT TILE 'INFO intrinsic prints a File Information 
Display on the standard output device, enabling you to determine the error number returned by 
FOPEN. Refer to Appendix A for a discussion of the File Information Display. 

The QUIT intrinsic call (statement 0001 3000 of Figure 4-6) aborts the program's process. The value 
of QUITND is 1 and this number is printed as a part of the resulting abort message, allowing you to 
determine, in the case of multiple QUITintrinsic calls in a program, which specific QUITcall was ex- 
ecuted. The system Job Control Word, JCW, is set to %100001 in this example. 

Opening a File on a Device Other Than Disc 

Figure 4-7 contains an SPL program that opens a card reader file and a disc file, reads the contents of 
a card deck and writes the records read from the card deck into the disc file and, finally, closes the 
disc file as a permanent file. 

If the desired card deck has been read in by the spooler before the program which references the deck 
executes, or if the :DATA card of that deck has been read by an unspooled card reader, the system 
finds an entry for the card reader file in the device directory and allocation is automatic. If the card 
deck is not read before the program executes , however , the system will print a message on the System 
Console requesting the System Operator to reply with the logical device number of the device on 
which the file resides. 

In Figure 4-7, statement 00010000: 

IN :=FDPENC INPUT, %5,,40,DEV); 

calls the FOPEN intrinsic to open the card reader file. The parameters specified are: 

formaldesignator INFILE, which is contained in the byte array INPUT. 

f options %5, for which the bit pattern is as follows: 

' ' ' ' ' "" ' ' ' *" ~" T ' ' BITS 

BINARY 
OCTAL 
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The above bit pattern specifies the following file options: 

Domain: Old permanent file, system file domain. Bits (14:2) = 01. 
ASCII/Binary: ASCII. Bit (13:3) = 1. 
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aoptions Omitted. All bits are set to zero . Access defaults to READ only. 

recsize 40 words. 

device CARD. The byte array DEV, containing the string "CARD ", is specified 

for the device parameter. 

All other parameters are omitted in the FQPEN call. 

Once the file is opened, the file number (used by other file system intrinsics when referencing this 
file) is returned to the variable IN. 

The next statement in the program (line 00011000 of Figure 4-7) checks the condition code. If the 
condition code is CCL, signifying that the FDPEN request was denied, the next four statements, start- 
ing with the BEG IN statement, are executed. 

Line 00013000 in Figure 4-7, PRINT 'FILE'INFOCIN); calls the PR I NT 'FILE 'INFO intrinsic, 
which prints a File Information Display on the standard list device, enabling you to determine the er- 
ror number returned by FQPEN. The parameter IN specifies the file number returned through the 
F0PEN intrinsic . If the file was not opened successfully, IN is set to 0, where specifies that the File 
Information Display will reflect the status of the file referenced in the last call to FOPEN. Refer to 
Appendix A for a discussion of the File Information Display. 

The QUIT intrinsic call in line 00014000 of Figure 4-7: 

QUITC1); 

aborts the process. The parameter 1 is an arbitrary user -specified number. When the program is 
terminated this number is displayed allowing you to determine, in the case of multiple QUIT intrinsic 
calls in a program, which specific QUIT call was executed. 

Using FREAD and FWRITE with $STDIN and $STDLIST 

If the standard input device ($STDIN) and the standard list device ($STDLIST) are opened with an 
FOPEN intrinsic call, the FREAD and FWRITE intrinsics can be used with these devices. For example, 
the FREAD intrinsic can be used to transfer information entered from a terminal to a buffer in the 
stack, and the FREAD intrinsic can be used to transfer information from a buffer in the stack directly 
to the standard list device . 
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PAGE 0001 


HP32100A 


.08.01 [4W] (C) HEWLETT-PACKARD COMPANY 1980 


00001000 


00000 





SCONTROL USLINIT 




00002000 


00000 





BEGIN 




00003000 


00000 


1 


BYTE ARRAY INPUT(0 :6 ) : ""INFILE " ; 




00004000 


00005 


1 


BYTE ARRAY DEV(0:4) 


""CARD "; 




00005000 


00004 


1 


BYTE ARRAY OUTPUT(0 


7):="DATA0NE "; 




00006000 


00005 


1 


ARRAY BUFFER(0:127) 






00007000 


00005 


1 


INTEGER IN, OUT, LGTH 






00008000 


00005 


1 


INTRINSIC FOPEN , FREAD , FWRITE , FCLOSE 


.PRINT'FILE'INFO.QUI 


00009000 


00005 


1 


<< END OF DECLARATIONS >> 




00010000 


00005 


1 


IN:=F0PEN(INPUT,%5, ,40,DEV) ; 


<<CARD READER>> 


00011000 


00012 


1 


IF < THEN 


<<CHECK FOR ERR0R>> 


00012000 


00013 


1 


BEGIN 




00013000 


00013 


2 


PRINT'FILE'INFO(IN) ; 


<<PRINT ERROR>> 


00014000 


00015 


2 


QUIT(l); 


<<ABORT>> 


00015000 


00017 


2 


END; 




00016000 


00017 


1 


OUT : =FOPEN ( OUTPUT , X4 , X101 , 128 ) ; 


<<NEW DISC FILE>> 


00017000 


00030 


1 


IF < THEN 


<<CHECK FOR ERR0R>> 


00018000 


00031 


1 


BEGIN 




00019000 


00031 


2 


PRINT'FILE'INFO(OUT); 


<<PRINT ERROR>> 


00020000 


00033 


2 


QUIT(2); 


<<ABORT>> 


00021000 


00035 


2 


END; 




00022000 


00035 


1 


COPY 'LOOP: 




00023000 


00035 


1 


LGTH : «FREAD( IN , BUFFER , 40 ) ; 


<<READ A CARD>> 


00024000 


00043 


1 


IF < THEN 


<<CHECK FOR ERR0R>> 


00025000 


00044 


1 


BEGIN 




00026000 


00044 


2 


PRINT'FILE'INFO(IN) ; 


<<PRINT ERROR>> 


00027000 


00046 


2 


QUITO); 


<<ABORT>> 


00028000 


00050 


2 


END; 




00029000 


00050 


1 


IF > THEN GO END 'OF 'FILE; 


<<CHECK FOR EOF>> 


00030000 


00051 


1 


FWRITE ( OUT , BUFFER , LGTH , ) ; 


<<C0PY CARD TO DISC 


00031000 


00056 


1 


IF < THEN 


<<CHECK FOR ERR0R>> 


00032000 


00057 


1 


BEGIN 




00033000 


00057 


2 


PRINT'FILE'INFO(OUT); 


<<PRINT ERROR>> 


00034000 


00061 


2 


QUIT(4); 


<<ABORT>> 


00035000 


00063 


2 


END; 




00036000 


00063 


1 


GO COPY' LOOP; 


<<CONTINUE COPYING) 


00037000 


00066 


1 


END 'OF 'FILE: 




00038000 


00066 


1 


FCL0SE(0UT,%1,0); 


<<MAKE PERMANENT>> 


00039000 


00072 


1 


IF < THEN 


<< CHECK FOR ERROR> 


00040000 


00073 


1 


BEGIN 




00041000 


00073 


2 


PRINT'FILE'INFO(OUT) ; 


<<PRINT ERROR>> 


00042000 


00075 


2 


QUIT(5); 


<<ABORT>> 


00043000 


00077 


2 


END; 




00044000 


00077 


1 


END; 





Figure 4-7. Opening a File on a Device Other Than Disc 
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OPENING SSTDIN. Figure 4-8 contains a program that opens $STDINso that FREAD intrinsic calls 
can be issued directly against the standard input device (in this case a terminal , since the program was 
run interactively). 

The standard input device is opened with the FDPEN intrinsic call : 

IN:=F0PENC,%244); 

The parameters specified in the above intrinsic call are as follows : 

formaldesignator Omitted. 

Default: A temporary nameless file, that can be read but not saved, is 
assigned . 



foptions 



%244, for which the bit pattern is as follows: 
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BITS 

BINARY 

OCTAL 

The above bit pattern specifies the following file options : 

Domain: New file. No search of system or job temporary file directory is 

necessary. Bits (14:2) = 00. 

ASCII/Binary : ASCII Bit ( 1 3 : 1 ) = 1 . 

Default Designator : $STDIN. Bits (10:3)= 100. 

Record Format: Undefined length. Bits (8:2) ■ 10. 

aoptions Omitted. All bits are set to zero, access defaults to READ only. 

All other parameters are omitted in the FOPEN intrinsic call. 

Since $STDIN is specified (bits (10:3)=100), MPE knows the file exists and ignores the new file 
specification without reporting an error . Once the file is opened , the file number (used by other file 
system intrinsics when referencing this file) is returned to the variable IN. 

The next statement in the program (00019000) checks the condition code. If the condition code is 
CCL, signifying that the FOPEN request was denied, the error -check procedure FILERRORis called. 

The F I LERRDR procedure (statements 00008000 through 00014000) calls the PRINT'FILE'INFD in- 
trinsic, which prints a File Information Display on the standard list device, enabling you to determine 
the error number returned by FDPEN. 

The QUITintrinsic call (statement 0001 3000 in Figure 4-8) aborts the process. 

OPENING SSTDLIST . In Figure 4- 8 , statement 00020000 : 

LIST:=F0PENC,%614,%1); 

opens the standard list device so that the FWRITE intrinsic can be used to transfer information directly 
to the device. 
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forma Idesignator 



f options 
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aoptions 



Omitted. 

Default : A temporary nameless file , that can be written on but not saved , 

is assigned. 

%61 4, for which the bit pattern is as follows: 



BITS 

BINARY 

OCTAL 



The preceding bit pattern specifies the following file options: 

Domain: New file. No search of system or job temporary file directory is 

necessary. Bits (14:2) = 00. 

ASCII/Binary: ASCII. Bit (13:1) =1. 

Default Designator: $STDLIST. Bits (10:3) = 001. 

Record Format: Undefined length. Bits (8:2) = 10. 

Carriage Control : Carriage control character expected. Bit (7:1)= 1 . 

%1 , for which the bit pattern is as follows: 



BITS 

BINARY 

OCTAL 



The preceding bit pattern specifies the following access options : 

Access Type: WRITE access only. Bits (12:4) = 0001 . 

All other parameters are omitted in the F0PEN intrinsic call. 

Once the file is opened, the file number (used by other file system intrinsics when referencing this 
file) is returned to the variable LIST. 

The next statement in the program (00021000 of Figure 4-8) checks the condition code. If the condi- 
tion code is CCL, signifying that the FDPEN request was denied, the error-check procedure FILERROR 
is called. 

The FILERROR procedure (statements 00008000 through 00014000 in Figure 4-8) calls the 
PR I NT 'FILE 'INFO intrinsic, which prints a File Information Display on the standard list device, 
enabling you to determine the error number returned by F0PEN. 

The QUIT intrinsic call (statement 00013000) aborts the process. 






1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 


15 











O 


O 


O 


O 


O 


O 


O 


O 


O 


O 


O 


O 


1 






























1 





4-26 



Accessing and Altering Files 



PAGE 0001 HP32100A.08.01 [4W] (C) HEWLETT-PACKARD COMPANY 1980 


00001000 


00000 





$C0NTR0L SUSLINIT 




00002000 


00000 





BEGIN 




00003000 


00000 


1 


BYTE ARRAY DATA1 (0 : 7 ) : ="DATA0NE "; 




00004000 


00005 


1 


ARRAY BUFFER(0:127) ; 




00005000 


00005 


1 


INTEGER DFILE 1 , LGTH , DUMMY , IN , LIST ; 




00006000 


00005 


1 


INTRINSIC FOPEN , FREAD , FUPDATE , FUNLOCK , FCLOSE , 


00007000 


00005 


1 


PRINT" FILE ' INFO , QUIT .FWRITE , FREAD ; 


00008000 


00005 


1 


PROCEDURE FILERROR(FILENO, QUITNO) ; 




00009000 


00000 


1 


VALUE QUITNO; 




00010000 


00000 


1 


INTEGER FILENO, QUITNO; 




00011000 


00000 


1 


BEGIN 




00012000 


00000 


2 


PRINT'FILE'INFO(FILENO) ; 




00013000 


00002 


2 


QUIT(QUITNO) ; 




00014000 


00004 


2 


END; 




00015000 


00000 


1 


<<END OF DECLARATIONS)) 




00016000 


00000 


1 


DFILE1:=F0PEN(DATA1,%5,%345,128) 


; <<OLD DISC FILE>> 


00017000 


00011 


1 


IF < THEN FILERR0R(DFILE1,1) ; 


<<CHECK FOR ERROR>> 


00018000 


00015 


1 


IN:=F0PEN( ,%244); 


<<$STDIN>> 


00019000 


00024 


1 


IF < THEN FILERROR(IN,2); 


<<CHECK FOR ERROR>> 


00020000 


00030 


1 


LIST:=FOPEN( ,%614,%1) ; 


<<$STDLIST>> 


00021000 


00040 


1 


IF < THEN FILERR0R(LIST,3) ; 


<<CHECK FOR ERROR>> 


00022000 


00044 


1 


UPDATE 'LOOP: 




00023000 


00044 


1 


FLOCK(DFILEl.l) ; 


<<L0CK FILE/SUSPEND>> 


00024000 


00047 


1 


IF < THEN FILERR0R(DFILE1,4) ; 


<<CHECK FOR ERROR>> 


00025000 


00053 


1 


LGTH :=FREAD(DFILE1, BUFFER, 128); 


<<GET EMPLOYEE RECD>> 


00026000 


00061 


1 


IF < THEN FILERR0R(DFILE1,5) ; 


<<CHECK FOR ERROR>> 


00027000 


00065 


1 


IF > THEN GO END'OF'FILE; 


<<CHECK FOR EOF>> 


00028000 


00070 


1 


FWRITE(LIST, BUFFER, -20, %320) ; 


<<EMPLOYEE NAME>> 


00029000 


00075 


1 


IF <> THEN FILERR0R(LIST,6); 


<<CHECK FOR ERROR>> 


00030000 


00101 


1 


DUMMY:=FREAD(IN,BUFFER(30) ,5) ; 


<<EMPLOYEE NUMBER) > 


00031000 


00110 


1 


IF < THEN FILERROR(IN,7) ; 


<<CHECK FOR ERROR>> 


00032000 


00114 


1 


IF > THEN GO END'OF'FILE; 




00034000 


00115 


1 


FUPDATE (DFILE1, BUFFER, 128); 


<<EMPLOYEE RECORD>> 


00035000 


00121 


1 


IF <> THEN FILERR0R(DFILE1,8) ; 


<<CHECK FOR ERROR>> 


00036000 


00125 


1 


FUNLOCK(DFILEl) ; 


<<ALLOW OTHER ACCESS) 


00037000 


00127 


1 


IF <> THEN FILERR0R(DFILE1,9) ; 


<<CHECK FOR ERROR)) 


00038000 


00133 


1 


GO UPDATE "LOOP; 


<<C0NTINUE UPDATE)) 


00039000 


00140 


1 


END'OF'FILE: 




00040000 


00140 


1 


FUNLOCK(DFILEl) ; 


<<ALLOW OTHER ACCESS) 


00041000 


00142 


1 


IF <> THEN FILERR0R(DFILE1,10); 


<<CHECK FOR ERROR)) 


00042000 


00146 


1 


FCLOSE(DFILE1,0,0) ; 


<<DISP-NO CHANGE) > 


00043000 


00151 


1 


IF < THEN FILERROR(DFILEl.ll) ; 


<<CHECK FOR ERROR)) 


00044000 


00155 


1 


END. 





Figure 4-8. Opening $STDIN and $STDLIST 
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CLOSING FILES 



To terminate access to a file , you use the FCLOSE intrinsic . The FCLDSE intrinsic applies to files on all 
devices, and deallocates the device on which the file resides. If a file has several concurrent FDPEN 
calls issued by the same user , the device is not deallocated until the last "nested " FCLDSE intrinsic is 
executed . 

The FCLDSE intrinsic may be used to change the disposition of a disc or magnetic tape file. For ex- 
ample , a file opened as a new file can be closed and saved as an old file with permanent or temporary 
disposition . Alternately , a disc file opened as a temporary file can be closed as temporary or saved as 
a permanent file. 

When the FDPEN intrinsic opens a disc file specified as new in the f opt ions parameter (bits (14:2) = 
00), neither the job temporary domain nor the system file domain is searched to ensure that a file of 
the same name does not exist already. However, if this file is saved with the FCLOSE intrinsic, a 
search is conducted. The job temporary file domain is searched if the file is to be saved as a tem- 
porary job/session file and the system file domain is searched if the file is to be saved as a permanent 
file. If a file of the same name is found in either directory, an error code is returned to the calling 
process. Thus, it is possible to open a new file with the same name as an existing file, but an error 
will occur if an FCLDSE intrinsic attempts to save such a file in the same domain with a file of the 
same name . 

Similarly , when the FOPEN intrinsic opens a file specified as an old temporary file in the f options 
parameter (bits (14:2) = 10), only the job temporary file domain (not the system file domain) is 
searched . Thus it is possible to have three files with the same name , a permanent file , a new file , and 
a temporary file. If a file opened as temporary is closed and saved as a permanent file with the 
FCLDSE intrinsic, the system file domain is searched. If a file of the same name is found, an error 
code is returned to the calling process . 

If an FCLOSE intrinsic call is not issued in a program in which files have been opened, MPE closes all 
files automatically when the program's process terminates. In this case, all opened files are closed 
with the same disposition they had before being opened . New files are deleted , old files are saved and 
assigned to the domain in which they belonged previously, either permanent or temporary. This may 
be altered, however, with a :FILE command. Further information on changing domains can be 
found in the MPE File System Reference Manual (30000-90236). The following examples illustrate 
how a new file can be closed as either a temporary file or a permanent file . 

Closing a New File as a Temporary File 

Figure 4-9 contains an FCLOSE intrinsic call that closes a new file as a temporary job file. 

The FCLOSE intrinsic call in statement 00036000: 

FCLDSECDFILE2,%2,0); 

closes the file specified by DFILE2. The parameters specified in the above intrinsic call are: 

filenton Contained in the identifier DFILE2. The file number was assigned to 

DFILE2when FOPEN opened the file. 

disposition %2, for which the bit pattern is as follows: 
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1 


2 


3 


4- 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14- 


15 












































1 

































2 





seocode 



BITS 

BINARY 

OCTAL 



The above bit pattern specifies the following: 

Domain Disposition: Temporary job file (rewound). The file is retained in 
the user's temporary (job/session) file domain and can thus be reopened by 
any process within the job/session. The uniqueness of the file name is 
checked; if a file of this name already exists in the job temporary file 
domain, an error code is returned. If the file resides on unlabeled magnetic 
tape, the tape is rewound, but not unloaded. However, if this is the last 
FCLOSE on the device, then the tape is rewound and unloaded. Bits (13:3) 
= 010. 

0. Unrestricted access. 



A condition code of CCL is returned if the file is not closed successfully. Statement 00037000: 

IF < THEN FILERRDR(DFILE2,7); 

checks the condition code. If the condition code is CCL, the error-check procedure FILERR0R 
(statements 0001 1000 through 00017000 in Figure 4-9) is called. The F I LERRDR procedure calls the 
PR I NT 'FILE' INFO intrinsic, which prints a File Information Display on the standard list device, 
enabling you to determine the error number returned to FCLOSE. 

The QUIT intrinsic call (00016000) aborts the process. 

The QUIT intrinsic causes MPE to close all files with no change. Thus new files are deleted, and old 
files are saved and assigned to the same domain to which they belonged previously, unless otherwise 
requested in a : F I LE command . 
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PAGE 0001 HP321 


00001000 


00000 





00002000 


00000 





00003000 


00000 


1 


00004000 


00005 


1 


00005000 


00005 


1 


00006000 


00011 


1 


00007000 


00011 


1 


00008000 


00011 


1 


00009000 


00011 


1 


00010000 


00011 


1 


00011000 


00011 


1 


00012000 


00000 


1 


00013000 


00000 


1 


00014000 


00000 


1 


00015000 


00000 


2 


00016000 


00002 


2 


00017000 


00004 


2 


00018000 


00000 


1 


00019000 


00000 


1 


00020000 


00010 


1 


00021000 


00014 


1 


00022000 


00027 


1 


00023000 


00033 


1 


00024000 


00041 


1 


00025000 


00045 


1 


00026000 


00053 


1 


00027000 


00057 


1 


00028000 


00057 


1 


00029000 


00065 


1 


00030000 


00071 


1 


00031000 


00072 


1 


00032000 


00076 


1 


00033000 


00103 


1 


00034000 


00107 


1 


00035000 


00116 


1 


00036000 


00116 


1 


00037000 


00122 


1 


00038000 


00126 


1 


00039000 


00132 


1 


00040000 


00136 


1 



00A.08.01 [4W] (C) HEWLETT-PACKARD COMPANY 1980 
$C0NTROL USLINIT 
BEGIN 

BYTE ARRAY DATA1(0 : 7 ) : ="DATAONE " ; 

BYTE ARRAY DATA2(0 : 7) : = "DATA TWO "; 

ARRAY LABL(0:8) :="EMPL0YEE DATA FILE"; 

ARRAY BUFFER(0:127); 

INTEGER DFILE1.DFILE2, DUMMY; 

DOUBLE REC; 

INTRINSIC FOPEN,FWRITELABEL,FGETINFO,FREAD,WRITEDIR,FCLOSE 

PRINT'FILE'INFO.QUIT; 
PROCEDURE FILERROR(FILENO,QUITNO) ; 
VALUE QUITNO; 
INTEGER FILENO.QUITNO; 
BEGIN 

PRINT'FILE'INFO(FILENO); 
QUIT(QUITNO); 
END; 
<<END OF DECLARATIONS>> 

DFILE1 : =F0PEN(DATA1 ,%5 ,Z100 ) ; 
IF < THEN FILERROR(DFILEl.l); 
DFILE2:=F0PEN(DATA2,%4,£4,128, , ,1) 
IF < THEN FILERROR(DFILE2,2J; 
FWRITELABEL(DFILE2,LABL,9,0); 
IF <> THEN FILERR0R(DFILE2,3) ; 

FGETINF0(DFILE1 , , , , REC) ; 

IF < THEN FILERR0R(DFILE1,4); 
INVERT 'LOOP: 

DUMMY :=FREAD(DFILE1, BUFFER, 128); 
IF < THEN FILERR0R(DFILE1,5); 
IF > THEN GO END 'OF 'FILE; 
REC:=REC-1D 

FWRITEDIR(DFILE2, BUFFER, 128, REC) ; 
IF <> THEN FILERR0R(DFILE2,6) ; 
GO INVERT 'LOOP; 
END'OF'FILE: 

FCLOSE(DFILE2,%2,0); 
IF < THEN FILERR0R{DFILE2,7); 
FCLOSE(DFILE1,4,0); 
IF <> THEN FILERR0R(DFILE1,8) ; 
END. 



<<OLD FILE-DATAONE> 
<<CHECK FOR ERROR>> 
;<<NEW FILE-DATATWO> 
<<CHECK FOR ERROR>> 
<<FILE ID>> 
<<CHECK FOR ERR0R>> 
<<LOCATE E0F>> 
<<CHECK FOR ERR0R>> 

<<OLD FILE RECORD>> 
<<CHECK FOR ERR0R>> 
<<CHECK FOR E0F>> 
<<LAST REDC N0>> 
<<INVERT REC 0RDER> 
<<CHECK FOR ERR0R>> 
<<CONTINUE OPERATIO 

<<SAVE NEW AS TEMP> 
<<CHECK FOR ERR0R>> 
<<DELETE OLD FILE>> 
<<CHECK FOR ERR0R>> 



Figure 4-9. Closing a New File as a Temporary File 
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Closing a New File as a Permanent File 

Figure 4-10 contains an FCLOSE intrinsic call that closes a new file as a permanent file. The FCLDSE 
intrinsic call in statement 00038000: 

FCL0SEC0UT,%11,0); 

closes the disc file specified by OUT. The parameters specified are : 



filenum 
disposition 



Contained in the identifier DUT. The file number was assigned to OUT 
when the FOPEN intrinsic opened the file. 

%1 1 , for which the bit pattern is as follows: 






1 


2 


3 


4- 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 


15 





























O 








1 


O 





1 
























1 






1 





seccode 



BITS 

BINARY 

OCTAL 



The above bit pattern specifies the following : 

Domain Disposition: Permanent file. The file is saved in the system 
domain. If the file is a new or old temporary file on disc, an entry is 
created for it in the system file directory. (An error code is returned if a 
file of the same name exists already in the system directory . ) If it is an old 
permanent file on disc, this disposition value has no effect. If the file is 
stored on magnetic tape, that tape is rewound and unloaded. Bits (13:3) = 
001. 

Disc Space Disposition: Unused disc space returned to the system. 
(Applicable to fixed and undefined length files only . ) Bits (12:1)= 1 . 

0. Unrestricted access. 



A condition code of CCL is returned if the file is not closed successfully. Statement 00039000 of 
Figure 4-10 checks the condition code and, if it is CCL, the next four statements, starting with the 
BEGIN statement, are executed. 

The PRINT 'FILE'INFO intrinsic which is called in statement 00041000 of Figure 4-10 prints a File 
Information Display on the standard list device , enabling you to determine the error number returned 
by FCLOSE. The QUITintrinsic call (00042000, Figure 4-10) aborts the process. 
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PAGE OOOJ 


l HP32100A.08 


01 [4W] (C) HEWLETT-PACKARD COMPANY 1980 


00001000 


00000 





$C0NTR0L USLINIT 




00002000 


00000 





BEGIN 






00003000 


00000 


1 


BYTE ARRAY INPUT(0:6 ) : ="INFILE " ; 




00004000 


00005 


1 


BYTE ARRAY DEV(0:4) 


="CARD "; 




00005000 


00004 


1 


BYTE ARRAY 0UTPUT(0 


7) :="DATAONE " 




00006000 


00005 


1 


ARRAY BUFFER(0:127) 






00007000 


00005 


1 


INTEGER IN.OUT.LGTH 






00008000 


00005 


1 


INTRINSIC FOPEN.FREAD.FWRITE.FCLOSE, PRINT 'FILE 'INFO, QUIT; 


00009000 


00005 


1 


<<END OF DECLARATIONS>> 




00010000 


00005 


1 




IN:=F0PEN(INPUT,%5, ,40,DEV) ; 


<<CARD READER>> 


00011000 


00012 


1 




IF < THEN 


<<CHECK FOR ERROR>> 


00012000 


00013 


1 




BEGIN 




00013000 


00013 


2 




PRINT'FILE'INFO(IN); 


<<PRINT ERR0R>> 


00014000 


00015 


2 




QUIT(l); 


<<ABORT>> 


00015000 


00017 


2 




END; 




00016000 


00017 


1 




OUT : =FOPEN (OUTPUT ,%4 , %101 , 128 ) 


;<<NEW DISC FILE>> 


00017000 


00030 


1 




IF < THEN 


<<CHECK FOR ERROR>> 


00018000 


00031 


1 




BEGIN 




00019000 


00031 


2 




PRINT'FILE'INFOIOUT) ; 


<<PRINT ERR0R>> 


00020000 


00033 


2 




QUIT(2); 


<<ABORT>> 


00021000 


00035 


2 




END; 




00022000 


00035 


1 


COPY'I 


.OOP: 




00023000 


00035 


1 




LGTH:=FREAD( IN, BUFFER, 40); 


<<READ A CARD>> 


00024000 


00043 


1 




IF < THEN 


<<CHECK FOR ERROR>> 


00025000 


00044 


1 




BEGIN 




00026000 


00044 


2 




PRINT'FILE'INFO(IN); 


<<PRINT ERR0R>> 


00027000 


00046 


2 




QUIT(3); 


<<ABORT>> 


00028000 


00050 


2 




END; 




00029000 


00050 


1 




IF > THEN GO END'OF'FILE; 


<<CHECK FOR EOF>> 


00030000 


00051 


1 




FWRITE ( OUT , BUFFER , LGTH , ) ; 


<<COPY CARD TO DISC>> 


00031000 


00056 


1 




IF <> THEN 


<<CHECK FOR ERROR>> 


00032000 


00057 


1 




BEGIN 




00033000 


00057 


2 




PRINT'FILE'INFOIOUT) ; 


<<PRINT ERR0R>> 


00034000 


00061 


2 




QUIT(4); 


<<ABORT>> 


00035000 


00063 


2 




END; 




00036000 


00063 


1 




GO COPY 'LOOP; 


<<C0NTINUE C0PYING>> 


00037000 


00066 


1 


END'OF'FILE: 




00038000 


00066 


1 




FCLOSE(OUT,%1,0) ; 


<<MAKE PERMANENT) > 


00039000 


00072 


1 




IF < THEN 


<<CHECK FOR ERROR>> 


00040000 


00073 


1 




BEGIN 




00041000 


00073 


2 




PRINT'FILE'INFOIOUT) ; 


<<PRINT ERR0R>> 


00042000 


00075 


2 




QUIT(5); 


<<ABORT>> 


00043000 


00077 


2 




END; 




00044000 


00077 


1 


END. 







Figure 4-10. Closing a New File as a Permanent File 
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WRITING A FILE SYSTEM ERROR -CHECK PROCEDURE 

As you noticed in some of the examples, the statements: 

BEGIN 

PRINT 'FILE 'INFOC/iZenwm); 

QUITCnum); 
END; 

were repeated after each intrinsic call. Instead of repeating this code throughout a program with mul- 
tiple intrinsic calls it is more efficient (because less code is generated) to write an error-check proce- 
dure and merely call this procedure where necessary in a program . 

Figure 4-11 contains a program which includes an error-check procedure, and a single statement 
calls this procedure if an error occurs. The program opens a card reader and a disc file, reads the card 
file, writes these records into the disc file, then closes the disc file. 

The error check procedure (statements 00009000 through 0001 5000 in Figure 4-11) contains two 
parameters: FILENO (integer) and QUITN0 (integer by value). FILEND is an identifier through which 
the file number is passed. This file number is used by PR I NT 'FILE 'INFO to print a File Information 
Display for that file. 

The QUIT intrinsic aborts the program's process and prints the QUITND as part of the abort message, 
enabling you to determine the point at which the process was aborted . 



USING FERRMSG 



This intrinsic is usually called following a call to FCHECK. The error code returned in the call to 
FCHECK can then be used as a parameter in the call to FERRMSG. 

For example, suppose a CCL condition is returned by a call to FCL0SE, a call to FCHECK requests the 
particular error code, then a call to FERRMSG can be used to retrieve a printable message associated 
with the code : 

FCLQSECFILENUM,1,(D; 
IF < 
THEN BEGIN 

FCHECKCFILENUM,ERRNUM>; 
FERRMSGCERRNUM, MESSAGE , LENGTH) ; 
PRINTCMESSAGE, -LENGTH, 0) ; 
END; 
TERMINATE; 

The message printed explains the FCHECK code. If the FCHECK code has no assigned meaning, the fol- 
lowing message is returned: 

UNDEFINED ERROR etvorcode 
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PAGE 0001 HP32100A.08.01 [4W] (C) HEWLETT-PACKARD COMPANY 1980 


00001000 


00000 





SCONTROL USLINIT 




00002000 


00000 





BEGIN 




00003000 


00000 


1 


BYTE ARRAY INPUT(0 : 6 ) : ="INFILE "; 




00004000 


00005 


1 


BYTE ARRAY DEV(0:4) 


="CARD "; 




00005000 


00004 


1 


BYTE ARRAY OUTPUT (0 


7) :="DATAONE "; 




00006000 


00005 


1 


ARRAY BUFFER (0:127) 






00007000 


00005 


1 


INTEGER IN.OUT.LGTH 






00008000 


00005 


1 


INTRINSIC FOPEN.FREAD.FWRITE.FCLOSE 


PRINT'FILE'INFO.QUIT; 


00009000 


00005 


1 


PROCEDURE FILERROR(FILENO, QUITNO) ; 




00010000 


00000 


1 


VALUE QUITNO; 




00011000 


00000 


1 


INTEGER FILENO, QUITNO; 




00012000 


00000 


1 


BEGIN 




00013000 


00000 


2 


PRINT'FILE'INFO(FILENO); 




00014000 


00002 


2 


QUIT(QUITNO); 




00015000 


00004 


2 


END; 




00016000 


00000 


1 


<<END OF DECLARATIONS>> 




00017000 


00000 


1 


IN:=FOPEN(INPUT,%5, ,40,DEV) ; 


<<CARD READER>> 


00018000 


00012 


1 


IF < THEN FILERROR(IN.l); 


<<CHECK FOR ERROR>> 


00019000 


0OO16 


1 


OUT:=FOPEN(OUTPUT,%4,%101,128) ; 


<<NEW DISC FILE>> 


00020000 


00027 


1 


IF < THEN FILERR0R(0UT,2); 


<<CHECK FOR ERROR> > 


00021000 


00033 


1 


COPY 'LOOP 




00022000 


00033 


1 


LGTH:=FREAD(IN. BUFFER, 40); 


<<READ A CARD>> 


00023000 


00041 


1 


IF < THEN FILERR0R(IN,3); 


<<CHECK FOR ERROR>> 


00024000 


00045 


1 


IF > THE GO END'OF'FILE; 


<<CHECK FOR EOF>> 


00025000 


00046 


1 


FWRITE(OUT,BUFFER,LGTH,0); 


<<COPY CARD TO DISC>> 


00026000 


00053 


1 


IF <> THEN FILERROR(0UT,4); 


<<CHECK FOR ERROR>> 


00027000 


00057 


1 


GO COPY' LOOP; 


<<CONTINUE COPYING>> 


00028000 


00062 


1 


END'OF'FILE: 




00029000 


00062 


1 


FCL0SE(0UT,%1,0) ; 


<<MAKE PERMANENT>> 


00030000 


00066 


1 


IF < THEN FILERR0R(0UT,5) ; 


<<CHECK FOR ERROR>> 


00031000 


00072 


1 


END. 





Figure 4-11. Error -Check Procedure Example 
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USING THE IOWAIT INTRINSIC 



Figure 4- 1 2 shows a program that opens several terminals for input. Statement 0001 6000: 

0UT:=FOPEN(OUTPUT,4,1 , ,DEV); 

opens the line printer for output and the WH I LE statement begins a loop to open the terminals . 

In order to open a file with both the NOBUF and NOW AIT aoptions specified, the program must be 
running in Privileged Mode , and this program is switched to Privileged Mode with the GETPR I VT10DE 
intrinsic call (statement 00019000, Figure 4-12). 

Statement 00029000 of Figure 4-12: 

FILE:=FOPENCTNAM ? %40S,%4404,36,DEVC3)); 

opens a terminal. The parameters specified are: 

foxmaldesignator DATA IN, which is contained in the byte array TNAM. 

%405, for which the bit pattern is: 



foptions 



aoptions 






1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 


15 























1 





O 











1 





1 


















4 













5 





BITS 

BINARY 

OCTAL 



The above bit pattern specifies the following file options : 

Domain: Old permanent file, system file domain. Bits (14:2) = 01 . 

ASCII/Binary : ASCII . Bit ( 1 3 : 1 ) = 1 . 

File Designator: Actual file designator ■ formal file designator. Bits 

(10:3) = 000. 

Record Format: Fixed -length records. Bits (8:2) ■ 00. 

Carriage Control : Carriage control character expected . Bit (7 : 1 ) = 1 . 

%4404, for which the bit pattern is as follows: 



BITS 

BINARY 

OCTAL 






1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 


15 














1 








1 

















1 


















4 






4 













4 





The above bit pattern specifies the following access options : 

Access Type: Input/output. Bits (12:4) = 0100. 
Multirecord: Non-multirecord. Bit (1 1 : 1 ) = 0. 



4-35 



Accessing and Altering Files 



Dynamic Locking : Disallowed . Bit ( 1 : 1 ) = 0. 

Exclusive: Exclusive access. Default when I/O access is specified. Bits 

(8:2) = 00. 

Inhibit Buffering: Selected (NDBUF). Bit (7: 1 ) = 1 . 

Multiaccess: No multiaccess. Bits (5:2) = 00. 

NO WAIT: NO WAIT I/O selected. Bit (4: 1 ) = 1 . 

recsize 36 words. 

device TERM (terminal), specified in elements (3)- (7) of the byte array DEV. 

Once the file is opened, the program is switched back to the non-Privileged Mode with the 
GETUSERMODE intrinsic call. 

The first file number is saved in FILEBASE, a prompt is displayed on the terminal, and the IOWA IT 
intrinsic is called to wait until the request is completed . Input from the terminal is read and stored in 
BUFR at the location determined by the file number. (Input from the first terminal opened starts at 
BUFR location 0, the next input starts at location 36, and so forth.) 

Statements 00029000/00030000 of Figure 4-12 wait for an end-of-file indication (the user enters 
an :E0F command) from the first terminal on which the input is complete. If the end-of-file indica- 
tion is received, the terminal is closed. 

The input from the terminal is printed on the line printer and another prompt is displayed. Again, 
the IOWA IT intrinsic is called to wait until the request is completed. When DQNE=MAXTRM (all ter- 
minals closed), control is passed to EX IT and the program terminates. 

Note that the 1 0D0NTWA I T intrinsic (not shown in Figure 4-12) operates the same way as IOWAIT 
with one exception: if IOWA IT is called and no I/O has completed, the calling process is suspended un- 
til some I/O completes; if IODONTWAITis called and no I/O has completed, control is returned to the 
calling process. Thus, the program shown in Figure 4-12 would not have suspended if the 
I ODONTWA IT intrinsic had been called, and control would have returned to the program. 
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PAGE 0001 


HP32100A.08.01 [4W] (C) HEWLETT-PACKARD COMPANY 1980 


00001000 


00000 





$CONTROL USLINIT 




00002000 


00000 





BEGIN 




00003000 


00000 


1 


BYTE ARRAY OUTPUT(0 :6 ) : ="OUTPUT 


; 


00004000 


00005 


1 


BYTE ARRAY TNAM(0 : 6 ) : ="DATAIN "; 




00005000 


00005 


1 


BYTE ARRAY DEV(0 :7 ) : ="LP TERM 




00006000 


00005 


1 


INTEGER 0UT,FILE,LGTH,I:=-1, PROMPT:*-"? ",DONE:=0; 


00007000 


00005 


1 


EQUATE MAXTRM=3; 




00008000 


00005 


1 


ARRAY BUFR(0:36*MAXTRM); 




00009000 


00005 


1 


INTEGER ARRAY OPEN(0 :MAXTRM) ; 




00010000 


00005 


1 


DEFINE CCL * IF < THEN QUIT#, 




00011000 


00005 


1 


CCG = IF > THEN QUIT#, 




00012000 


00005 


1 


CCNE= IF <> THEN QUIT*; 




00013000 


00005 


1 


INTRINSIC FOPEN,FREAD,FWRITE,FCL0SE,GETPRIVMODE,GETUSERM0D 


00014000 


00005 


1 


IOWAIT.QUIT; 




00015000 


00005 


1 


<<END OF DECLARATIONS>> 




00016000 


00005 


1 


0UT:=F0PEN(0UTPUT,4,1, ,DEV); CCL( 1) ; <<LINEPRINTER OUTPUT 


00017000 


00015 


1 


WHILE (I:=I+1)<MAXTRM DO 


<<LOOP-SET UP TERMS>> 


00018000 


00023 


1 


BEGIN 




00019000 


00023 


2 


GETPRIVMODE; CCG (2) ; 


<<FOR NOWAIT F0PEN>> 


00020000 


00027 


2 


FILE:=FOPEN(TNAM,%405,%4404,36,DEV(3));<<INPUT TERM> 


00021000 


00042 


2 


CCL(3); 


<<CHECK FOR ERROR >> 


00022000 


00045 


2 


GETUSERMODE; CCG (4) ; 


<<F0R NOWAIT I/0>> 


00023000 


00051 


2 


OPEN(I) :=FILE; 


<<SAVE FILE NUMBERS>> 


00024000 


00054 


2 


FWRITEf FILE . PROMPT , 1 , %320 ) 


;CCNE(5); <<OUTPUT ? PROMPT 


00025000 


00064 


2 


IOWAIT(FILE) ; CCNE(6) ; 


<<COMPLETE REQUEST>> 


00026000 


00075 


2 


FREAD(FILE,BUFR(I*36) ,-72) 


;CCNE(7);<<INPUT DATA-NOWA 


00027000 


00111 


2 


END; 




00028000 


00116 


1 


WAIT; 




00029000 


00116 


1 


FILE:=IOWAIT(0, ,LGTH); CCL(8); 


<<WAIT FOR 1ST D0NE>> 


00030000 


00130 


1 


IF > THEN 


<<EOF ON TERM READ>> 


00031000 


00131 


1 


BEGIN 




00032000 


00131 


2 


FCLOSE(FILE,0,0); CCL(9) ; 


<<TERMINAL FILE>> 


00033000 


00137 


2 


IF(D0NE:=D0NE+1)>=MAXTRM THEN GO EXIT;<<TERMS CLSD?> 


00034000 


00143 


2 


END 




00035000 


00143 


1 


ELSE 




00036000 


00145 


1 


BEGIN 




00037000 


00145 


2 


I:— 1; 


<<SET BUFFER INDEX>> 


00038000 


00147 


2 


DO I:-I+l 


<<INCR BUFFER INDEX>> 


00039000 


00147 


2 


UNTIL OPEN(I)*FILE OR 1= 


*IAXTRM;<<SEARCH FOR FILE N 


00040000 


00157 


2 


IF I-MAXTRM THEN QUIT{10); 


<<FILE NOT FOUND>> 


00041000 


00164 


2 


FWRITE( OUT, BUFR( 1*36) ,-LGTH ,0 ) ; <<COPY INPUT TO LP>> 


00042000 


00174 


2 


CCNE(ll); 


<<CHECK FOR ERROR>> 


00043000 


00177 


2 


FWRITE(FILE , PROMPT, 1 ,%320) 


;CCNE(12) ;<<OUTPUT ? PROMP 


00044000 


00207 


2 


IOWAIT(FILE) ; CCNE(13); 


<<COMPLETE REQUEST>> 


00045000 


00220 


2 


FREAD (FILE, BUFR( 1*36), -72) 


;CCNE(14) ;<<IN DATA-NOWAIT 


00046000 


00234 


2 


END; 




00047000 


00234 


1 


GO TO WAIT; 


<<CONTINUE>> 


00048000 


00235 


1 


EXIT;END. 





Figure 4-12. Using the IOWAIT Intrinsic 
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DECLARING ACCESS-MODE OPTIONS 

You can activate or deactivate the following access -mode options by issuing the FSETMQDE intrinsic 
call: automatic error recovery, critical output verification, terminal control by the user, and ter- 
minal binary data mode. The access modes that are established remain in effect until another 
FSETMODE call is issued or until the file is closed. The FSETMODE intrinsic applies to all files on all 
devices. 

The following FSETMODE intrinsic call: 

FSETMODE (F I LE1,%2); 

establishes access -mode options as outlined below. The parameters specified are: 



filenum 
modeflags 



Designated by FILE1, which was assigned the file number by FOPEN when 
the file was opened . (It is a terminal in this example . ) 

%2, for which the bit pattern is as follows: 






1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


1 + 


15 












































1 

































2 





BITS 

BINARY 

OCTAL 



The above bit pattern specifies the following access-mode options: 

Critical Output Verification : All physical output of blocks to the file is to 
be verified as physically complete before control returns from a write in- 
trinsic to your program. For each successful logical write operation, a con- 
dition code (CCE) is returned immediately to your program. Bit (14:1) = 
1. 

Terminal Control by User : MPE will issue carriage return/linefeed . 
Bit (13:1) = 0. 
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SECTION 



MPE intrinsics allow you to perform the following utility functions : 

• Manage library procedures with LOADPROC and UNLOADPROC. 

• Convert numbers from ASCII to binary code with BINARY and DBINARY. 

• Convert numbers from binary to ASCII code with ASCI I and DASCI I. 

• Convert a string of characters between EBCDIC and ASCII, or between EBCDIK and JIS 
(KANA8) with CTRANSLATE. 

• Read input from job/session list devices with READ and READX. 

• Write output to the job/session list device with PRINT. 

• Write output to the System Console with PRINTDP, or write output to the System Console and 
solicit a reply with PRINTDPREPLY. 

• Obtain system timer information with TIMER. 

• Obtain the calendar date with CALENDAR. 

• Obtain the time of day in terms of hour , minute , second , and tenth of second with CLQCK. 

• Format the calendar date with FMTCALENDAR. 

• Format the time of day with FMTCLOCK. 

• Format the calendar date and time of day with FMTDATE. 

• Obtain process run time (CPU time) with PROCTIME. 

• Obtain information pertaining to your access mode and attributes with WHD. 
Obtain information about other jobs/sessions in the system with JDBINFD. 

• Search an array for a specified name with SEARCH. 
Format the parameters of a non-MPE command with MYCDMMAND. 

• Execute MPE commands programmatically with COMMAND. 
« Enable or disable hardware arithmetic traps with ARITRAP. 

• Enable or disable software arithmetic traps with XARITRAP. 

• Enable or disable the software library trap with XLIBTRAP. 

• Enable or disable the software system trap with XSYSTRAP. 
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• Enable/disable the CONTROL-Y trap with XCONTRAP and reset a terminal to accept a 
CONTROL-Y signal with RESETCDNTROL. 

• Change the size of the current DL to DB area with DLSIZE. 

• Change the size of the current Z to DB area with ZSIZE. 

• Suspend the calling process with PAUSE. 

• Initiate a session break programmatically with CAUSEBREAK. 

• Programmatically terminate a process (after successful execution) with TERMINATE. 

• Programmatically abort any process within a user process structure with QUIT. 
© Abort the entire process structure (program) with QUITPROG. 

• Manage Interprocess Communication through the Job Control Words with SETJCW, GETJCW, 
PUTJCH, andFINDJCH. 

• Access a message catalog in the MPE message facility , and insert parameters in a message , with 
the GENMESSAGE intrinsic. 

• Control the functioning of an HP 2680/2688 page printer with FDEVICECONTROL 

DYNAMIC LOADING AND UNLOADING OF LIBRARY PROCEDURES 

Normally , segments containing library procedures referenced by a program are linked to that program 
when the program is loaded. However, you can also dynamically link and unlink such procedures 
while your program is running. You might, for example, decide to do this for a large procedure used 
optionally and infrequently by your program, or for a procedure whose name is not known at load 
time. By loading this procedure only when it is required, and then unloading it, you can save the 
table entries since these segments are sharable. The procedures are loaded from segmented libraries, 
not from relocatable libraries (which are used only at program preparation time). Preparation and 
maintenance of segmented libraries and relocatable libraries is explained in the MPE Segmenter 
Reference Manual (30000-9001 1). 

You do not need to dynamically load procedures that are declared as externals to your program, be- 
cause the loader will load them automatically. Dynamic loading and unloading is intended for 
procedures that are not declared at all. 
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Dynamic Loading 

The LQADPROC intrinsic is used to load a library procedure, together with external procedures 
referenced by it. 

For example, to dynamically load a procedure named PRDC1 , enter the following intrinsic call: 

PNUM : =LOADPROCCPNAME , , LAB) ; 

The parameters specified in the preceding intrinsic call are : 

procname Contained in the byte array PNAME. The contents of PNAME is the string 

"PRDC1 ". Note that the string is terminated with a blank space. 

lib 0, signifying that only the system library should be searched. If 2 were 

specified , library searching would proceed in this order : 

Logon Group Library 
Logon Account Library 
System Library 

Specifying 1 for the lib parameter would cause the search to be conducted 
in this order: 

Account Public Library 
System Library 

plabel LAB, a word to which the procedure's label ("plabel") is returned. 

When the LOADPROC intrinsic executes, the procedure identity number will be returned as an integer 
to PNUM. 

Dynamic Unloading 

The UNLDADPROC intrinsic is used to unload a procedure and its referenced external procedures. 

For example, to unload the procedure that was dynamically loaded in the previous example, enter the 
following UNLDADPROC intrinsic call: 

UNLDADPROC CPNUM); 
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SEARCHING ARRAYS 



Occasionally, you may construct byte arrays whose contents you may later want to search for 
specified entries or names. A dictionary of user-defined commands (UDCs) is one such example. 
The searching is accomplished with the SEARCH intrinsic , which can be used with specially formatted 
arrays consisting of sequential entries, each including: 

• An integer specifying the length (in bytes) of the entire entry. The length includes this byte, plus 
all the information in the subsequent byte areas. 

• An integer specifying the length of the "name" (in bytes) in the entry. 

• A byte string forming the name in the entry ; this name and name length are checked against the 
search string for a match. In a command dictionary, for example, this would be a command 
name. 

• An optional byte string containing a user -supplied definition. 

• A zero, as the length of the last entry, indicating the end of the dictionary. 

Each entry has an implied entry number in the dictionary. The entry number of the first entry in 
such a dictionary is one (1 ). If the entry is not found, zero (0) is returned by SEARCH. 

In the examples below, the five rows all represent entries for the SEARCH intrinsic. The elements of 
each row (except the last) are the length of the entry, the length of the "name", the byte string, and 
the user -supplied definition. In the last row, the zero indicates the end of the array (but is not ac- 
tually part of the array contents). 

EXAMPLE 1 : 

BYTE ARRAY CDMMANDTABLE CO: 25):= 

5,2,"IN",1, 

6,3,"0UT",1, 

7,4, "SKIP", 2, 

7, 4, "EXIT", 0, 

0; 

The main program might use the definitions as a cross-reference, to indicate the type of parameter 
which the user might enter after a prompt: f or no parameter, 1 for a filename, and 2 for a 
number. 

EXAMPLE 2: 

BYTE ARRAY SHDRTCQfflANDS (0:29):= 

5,1,"r',"IN", 

6,1,"D","0UT", 

7,1,"S","SKIP", 

7,1,"E","EXIT", 

0; 

The main program might use this array as a cross-reference table, to allow abbreviated commands to 
be entered by the user . 



5-4 



Other Applications Of MPE Intrinsics 



EXAMPLE 3 : 



BYTE ARRAY RESPONSETABLE (0:9):= 
5, 3, "YES", 
4, 2, "NO", 
0; 

This look-up table would allow the user to enter YES or NO as responses to prompts. No definitions 
were necessary in this example . 

You can request the search of such an array for a specified name with the SEARCH intrinsic. A simple 
linear search is performed , with the name , specified as a byte array , compared against the byte array 
forming the name in each entry. Because the search is linear, the most frequently used byte arrays 
should appear at the beginning of the array to promote efficient searching . If the name is found , the 
number of the entry containing the name is returned to the calling program. If the name is not 
found, a zero is returned. Optionally, you can also request the return of a pointer to the definition 
information for the name. 

If you want to search the byte array in Example 1 for the string " IN", the following intrinsic call 
could be used : 

BYTE ARRAY COMMAND (0:3);MOVE COMMAND: -" IN "; 
ENUM : =SEARCH CCOMMAND, 2 , COMMANDTABLE , DEFADDR ) ; 

The length of the string in COMMAND is two bytes. The byte address of the definition sought is to be 
returned to the word DEFADDR. The entry number corresponding to the entry containing " IN" will 
be returned to the word ENUM. 



FORMATTING COMMAND PARAMETERS 



You can programmatically extract and format for execution the parameters of a command defined by 
you (that is, the command is not an MPE command) with the MYCOMMAND intrinsic . Additionally, 
you can have the MYCOMMAND intrinsic search a byte array for the specified command. Figure 5-1 
contains a program that determines whether the user is running the program in a session, and if so, 
performs the following : 

• Prompts the user to enter a command name from the terminal. 

• Reads the command name entered by the user . 

• Compares this command name against entries in a byte array . If no match is found , the program 
displays " ILLEGAL ENTRY", and prompts the user for another command. 

» Converts the parameter entered with the command to binary, then uses this operand to perform 
the calculation specified by the command. 

• Converts the result to ASCII, then displays the result on the terminal. 
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PAGE 0001 


HEWLETT-PACKARD 32100A.08.1 SPL[4W] TUE , OCT 28 


1982, 4:35 PM 


00001000 


00000 





$CONTR0L USLINIT 




00002000 


00000 





BEGIN 




00003000 


00000 


1 


ARRAY HEADING(0:8):="INTEGER CALCULATOR"; 




00004000 


00011 


1 


ARRAY ERRMSG(0:6) :="ILLEGAL ENTRY."; 




00005000 


00007 


1 


ARRAY INPUT(0:36) ; 




00006000 


00007 


1 


BYTE ARRAY COMMAND (*)= INPUT ; 




00007000 


00007 


1 


BYTE ARRAY ANSWER (0 : 13) : ="ACCUM * " ; 




00008000 


00010 


1 


ARRAY OUTPUT (*) "ANSWER; 




00009000 


00010 


1 


BYTE ARRAY TABLE (0 :25 ) ; = 




00010000 


00001 


1 


5, 3, "ADD", 5, 3, "SUB", 5,3,"MUL", 


00011000 


00010 


1 


5,3,"DIV" , 5, 3, "SET", 0; 




00012000 


00016 


1 


INTEGER ARRAY PARMINFO(0 : 1 ) ; 




00013000 


00016 


1 


LOGICAL INTERACTIVE :=FALSE; 




00014000 


00016 


1 


INTEGER ACCUM: =0, OPERAND: =0, REQ:="? ", 




00015000 


00016 


1 


LGTH, INDX, PARMCNT, 


TYPE; 


00016000 


00016 


1 






00017000 


00016 


1 


INTR INSIC ASCII , BINARY , READ , PR INT , MYCOMMAND , QUIT , WHO ; 


00018000 


00016 


1 






00019000 


00016 


1 


<<END OF DECLARATIONS>> 




00020000 


00016 


1 






00021000 


00016 


1 


PRINT(HEADING,9,0); 


<<PROGRAM ID>> 


00022000 


00004 


1 


WHO (INTERACTIVE) ; 


<<LIVE USER?>> 


00023000 


00010 


1 


LOOP: 




00024000 


00010 


1 


IF INTERACTIVE THEN PRINT( REQ, 1 ,%320 ) ; 


<<PROMPT USER>> 


00025000 


0O016 


1 


LGTH:=READ(INPUT,-72) ; 


<<GET C0MD>> 


00026000 


00023 


1 


IF <> THEN QUIT(l); 


<<CHECK FOR ERR>> 


00027000 


00026 


1 


IF COMMAND ="END" THEN GO EXIT; 


<<DONE - EXIT>> 


00028000 


00040 


1 


COMMAND (LGTH) :=%15; 


<<CARRIAGE RETN>> 


00029000 


00043 


1 






00030000 


00043 


1 


TYPE : =MYCOMMAND ( COMMAND , , 1 , PARMCNT , 


<<TAKE APART CMD>> 


00031000 


00050 


1 


PARMINFO, TABLE) ; 




00032000 


00056 


1 


IF < THEN GO ERROR; 


<<N0 CMD MATCH>> 


00033000 


00057 


1 


IF PARMCNTol THEN GO ERROR; 


<<NO PARAMETERS>> 


00034000 


00062 


1 


INDX : =PARMINFO-<aCOMMAND ; 


<<SUBSCR OF PARM>> 


00035000 


00065 


1 


OPERAND:=BINARY(COMMAND(INDX) , 


<<C0NVERT PARM>> 


00036000 


00070 


1 


PARMINFO(l) .(0:8)) ; 




00037000 


00075 


1 


IF <> THEN GO ERROR; 


<<CHECK FOR ERR>> 


00038100 


00076 


1 






00039000 


00076 


1 


CASE (TYPE-1) OF 


<<SELECT OPERATN>> 


00040000 


00100 


1 


BEGIN 




00041000 


00106 


2 


ACCUM 


=ACCUM+OPERAND 




<<ADD COMD>> 


00042000 


00116 


2 


ACCUM 


=ACCUM-OPERAND 




<<SUB COMD>> 


00043000 


00122 


2 


ACCUM 


=ACCUM*OPERAND 




<<MUL COMD>> 


00044000 


00126 


2 


ACCUM 


=ACCUM/OPERAND 




<<DIV COMMAND>> 


00045000 


00133 


2 


ACCUM 


^OPERAND; 


<<SET COMMAND >> 


00046000 


00136 


2 


END; 





Figure 5-1 . Using the MYCOMMAND Intrinsic (Program UTILY) (1 of 2) 
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00047000 


00143 


1 


RESULT: 




00048000 


00143 


1 


MOVE ANSWER (8):=" 


<<RESET OLD ANSWER>> 


00049000 


00155 


1 


ASCII ( ACCUM , 10 , ANSWER ( 8 ) ) ; 


<<CONVERT ACCUM>> 


00050000 


00163 


1 


PRINT(OUTPUT,7,0); 


<<OUTPUT NEW ANSWER>> 


00051000 


00170 


1 


GO LOOP; 


<<C0NTINUE CALC>> 


00052000 


00171 


1 


ERROR: 




00053000 


00171 


1 


PRINT(ERRMSG,7,0); 


<<ERROR MESSAGE>> 


00054000 


00175 


1 


IF NOT INTERACTIVE THEN QUIT(2); 


<<N0 LIVE USER-QUIT>> 


00055000 


00201 


1 


GO LOOP; 


<<C0NTINUE CALC>> 


00056000 


00202 


1 


EXIT: END. 




PRIMARY 


DB STORAGE=%020; SECONDARY DB ST0RAGE=%00113 




NO. ERRORS=000; 


NO. WARNINGS=000 




PROCESSOR TIME=0 


00:03; ELAPSED TIME=0:00:11 





Figure 5-1. Using the MYCOMMAND Intrinsic (Program UTILY) (2 of 2) 

Statement 00025000: 

LGTH:=READ(INPUT,-72); 

reads the command entered by the user. (The arrays INPUT and COMMAND have been set as equivalents 
in statement 00006000 in Figure 5-1 ,) 

Statements 00026000 and 00027000: 



IF <> THEN QUIT(1>; 

IF CDMMAND="END" THEN GO EXIT; 

perform the following: 

• Check for a condition code error and execute the QUIT intrinsic (causing the process to abort if a 
condition code error is returned) . 

• Cause the program control to transfer to the statement EXIT if " END" is entered by the user. 
Statement 00028000: 

C0MMANDCLGTH):=X15; 

adds a carriage return character as the last character of the comimage parameter for the command en- 
tered. The carriage return character is added starting at the position in the array specified by LGTH, 
but does not overwrite the last position of the string entered by the user. This is because in SPL, the 
first position in an array is , not 1 . For example , if the user entered the command ADD 5, this 
command would occupy array positions through 4 , as follows : 

12 3 4 
ADD 5 

The value returned to LGTH specifying the length of the string read , however , is 5 , because the READ 
statement read a string five characters long. Therefore, the carriage return character is added to 
position 5 of the array (which is actually the 6th position). 
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Statement 00030000: 

TYPE:=MYC0NMANDCC0I*T1AND 7 ,1 ,PARMCNT,PARMINFO, TABLE); 

calls the MYCOrtlAND intrinsic to parse the command entered by the user. The parameters specified 
are: 



comvmage 



delimiters 

rraxparms 
numparms 

parms 



Specified by the array COMMAND. It contains the string entered by the user . 
This parameter contains a user command , such as ADD or SUB, a parameter 
consisting of an integer, and a carriage return character added to the com- 
mand by the statement : 

C0MMANDCLGTH):=%15; 

Omitted. The default delimiter array "C0M1A, EQUAL, SEMICOLON, 
CARRIAGE RETURN" is used. 

1 , specifying that one parameter is expected in comimage . 

Specified by PARMCNT. It contains the actual number of parameters en- 
tered with the command. 

Specified by PARMINFQ. An integer array to which the byte address of the 
parameter, entered as part of comimage, is returned. 



diet 



NOTE 



Although this parameter is listed as a double array in the 
specifications for the MYCDMMAND intrinsic in Section II , 
it is declared as a two -word integer array in this 
program because it is necessary to access each of the 
words individually. This is more convenient than 
declaring a one-word double array and a two-word in- 
teger array, then setting the two as equivalents. 



Specified by TABLE, a byte array containing "5,3, "ADD", 5, 3, "SUB", 
5,3," MUL", 5,3,"DIV", 5, 3, "SET", 0". 



The table specified by the diet parameter is searched until a match is found between the command 
name and an entry in the table. When a match is found, the number of the entry in the table con- 
taining the matching name is returned to TYPE. The diet parameter may specify a specially formatted 
array , or table . Each entry in the table will contain : 

1 . An integer specifying the total number of bytes in the entry. 

2. An integer specifying the total number of characters in the command portion of the entry. 
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3. The command portion of the entry. 

4. An arbitrary user -defined definition of the entry. 
For example , the first entry in the array TABLE is : 

5, 3, ADD 

which is broken down as follows : 

5 The total number of bytes in this entry (53ADD= 5 bytes). 

3 The total number of bytes in the command portion (ADD) of the entry. 

ADD The string comprising the command portion of the entry. 

Note that a user-defined definition of the entry is not included in the entries in TABLE. The byte ar- 
ray TABLE, then, consists of 26 bytes structured as follows: 



5 


3 


A 


D 


D 


5 


3 


S 


U 


B 


5 


3 


M 


U 


L 


5 


3 


D 


I 


V 


5 


3 


S 


E 


T 
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Statement 00032000: 

IF < THEN GO ERROR; 
checks the condition code, and if it is CCL, transfers program control to statement label ERROR. 
Statement 00033000: 

IF PARMCNT <> 1 THEN GO ERROR; 

checks that only one parameter was entered with the command (the parameter maxparms had 
specified that one parameter was expected). If PARMCNT does not equal 1, control is transferred to 
statement label ERROR. 

Statements 00034000 and 00035000: 

INDX : =PARMINF0-@C0mAND; 

OPERAND: =BINARY(CDMMAND(INDX),PARMINF0(1 ). (0:8)); 

determine the byte address of the parameter entered with the command , then convert this parameter 
to a binary value . 

The first statement above subtracts the byte address of the first element of COMMAND from the byte 
address of PARMINF0 to obtain the relative position of the parameter in the array COMMAND. This 
value is returned to INDX. 

For example , the command : 

ADD 5 

would occupy positions in the array COMMAND as follows : 

12 3 4 
ADD E 

Subtracting the byte address of the first (zero) element of COMMAND from the byte address specified by 
PARMINF0 for the first element of the parameter produces the byte offset of the parameter. 

The following statement converts the ASCII characters starting in the INDX position of the array 
COMMAND to a binary value and returns this value to OPERAND. The number of bytes (length) of the 
ASCII string to be converted are specified by the first eight bits (PARMINF0C1 ). (0:8)) of the first 
word contained in PARMINF0: 

OPERAND: =BINARY(CDMMAND(INDX),PARMINF0(1). (0:8)); 

The following statement transfers program control to one of the five statements following the BEGIN 
statement, depending on the value of TYPE-1. Note that -1 is necessary because the five statements 
are considered in the SPL numbering convention by the CASE statement (ACCUM:=ACCUM+OPERAND; 
is considered to be the statement following BEGIN) but the value assigned to TYPE by MYCOMMAND 
contains the range 1 to 5 : 

CASE(TYPE-1 )0F 
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An example of running the program is shown below . 

: RUN UTILY 

INTEGER CALCULATOR 

? SET 10 

ACCUM = 10 

? ADD 34 

ACCUM = 44 

? MUL .5 

ILLEGAL ENTRY 

? MUL 2 

ACCUM = 88 

? END 

END OF PROGRAM 



EXECUTING MPE COMMANDS PROGRAMMATICALLY 



The COMMAND intrinsic can be used to programmatically request the execution of certain MPE com- 
mands. The command image, including parameters, is passed to the intrinsic, which searches the sys- 
tem command directory for a command of the same name, and executes it. When command execu- 
tion is completed, or when an error is detected during this execution, control returns to the calling 
process. Commands that can be executed programmatically are listed below. 

LOG 

MPLINE 

MRJECONTROL 

NEWACCT 

NEWGRDUP 

NEWUSER 

NEWVSET 

OUTFENCE 

PTAPE 

PURGE 

PURGEACCT 

PURGEGROUP 

PURGEUSER 

PURGEVSET 

RECALL 

REFUSE 

RELEASE 

RELLOG 

REMOTE 

REMOTE HELLO 

RENAME 

REPLY 

REPORT 

RESET 

RESETACCT 

RESETDUMP 



ABORT 10 


:DSCONTR0L 


ABORTJOB 


:DSLINE 


ACCEPT 


•DSTAT 


ALLOW 


FILE 


ALTACCT 


FOREIGN 


ALTGROUP 


GETLOG 


ALTJOB 


GETRIN 


ALTLOG 


GIVE 


ALTSEC 


HEADOFF 


ALTSPOOLFILE 


HEADON 


ALTUSER 


HELP 


ALTVSET 


IMLCONTROL 


ASSOCIATE 


JOBFENCE 


BREAKJOB 


JOBPRI 


BUILD 


JOBSECURITY 


CACHECONTROL 


LDISMOUNT 


CHANGELOG 


LIMIT 


COMMENT 


LISTACCT 


CONSOLE 


LISTEQ 


DEALLOCATE : 


LISTF 


DELETESPOOLFILE : 


LISTFTEMP 


DISALLOW : 


LISTGROUP 


DISASSOCIATE : 


LISTLOG 


DICSRPS : 


LISTUSER 


DOWN : 


LISTVS 


DOWNLOAD : 


LMOUNT 
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RESUME JOB 

RESUMELOG 

RESUMESPOOL 

SAVE 

SECURE 

SETDUMP 

SETJCW 

SETMSG 

SHOWALLOW 

SHOWCACHE 

SHOWCOM 

SHOWDEV 



SHOW IN 

SHOWJCW 

SHOWJOB 

SHDWLOG 

SHOWME 

SHOWOUT 

SHOWQ 

SHOWTIME 

SPEED 

STARTCACHE 

STARTSPOOL 

STOPCACHE 



STOPSPOOL 

STREAM 

SUSPENDSPOOL 

SWITCHLOG 

TAKE 

TELL 

TELLOP 

TUNE 

UP 

VMOUNT 

WARN 

WELCOME 



Refer to the MPE V Commands Reference Manual (32033-90006) for a discussion of these 
commands. 

If you want to programmatically execute the command : SHOWTIME, the following intrinsic call could 
be used : 

COMMANDCCQMD,ECODE,EPARM) ; 

All characters for the command except the prompting colon but including a terminating carriage 
return are contained in the byte array COMD. Any error code is returned to ECODE. The : SHOWTIME 
command has no parameters, therefore, no information is returned to EPARM. 

When the intrinsic executes, the date and time are printed on the job/session list device. 



DETERMINING THE USER'S ACCESS MODE AND ATTRIBUTES 



A program can obtain the access mode and attributes of the user running that program from the sys- 
tem tables with the WHO intrinsic. 

Figure 5-2 contains a program which must determine if the user is running the program in an inter- 
active session . The statement : 

WHO (INTERACTIVE); 

calls the WHO intrinsic to make this determination. If the logical identifier INTERACTIVE is TRUE (bit 
(15:1) = 1) after the WHO intrinsic executes, and the job/session input file and job/session list file 
form an interactive pair, then the user is running the program interactively. 

Statement 00024000: 

IF INTERACTIVE THEN PRINT(REQ,1 ,%3?0); 

checks whether INTERACTIVE is TRUE or FALSE. If TRUE, the PR I NT portion of the statement is ex- 
ecuted and a prompt character (?) is displayed on the terminal to prompt the user for a command. 
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00015000 

00016000 

00017000 
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00019000 

00020000 

00021000 

00022000 

00023000 

00024000 

00025000 

00026000 

00027000 

00028000 

00029000 
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00031000 

00032000 
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HEWLETT-PACKARD 32100A.08.1 SPL[4W] TUE , OCT 28, 1982, 4:35 PM 
00000 $C0NTR0L USLINIT 
BEGIN 

ARRAY HEADING(0: 8) —"INTEGER CALCULATOR"; 

ARRAY ERRMSG(0:6):="ILLEGAL ENTRY."; 

ARRAY INPUT(0:36); 

BYTE ARRAY C0MMAND{*) =INPUT ; 

BYTE ARRAY ANSWER (0 : 13 ): ="ACCUM = "; 

ARRAY OUTPUT(*)=ANSWER; 

BYTE ARRAY TABLE (0:25) := 

5, 3, "ADD", 5,3, "SUB", 5,3,"MUL M , 
5,3,"DIV" , 5,3,"SET" , 0; 
INTEGER ARRAY PARMINF0(0 : 1 ) ; 
LOGICAL INTERACTIVE :=FALSE; 
INTEGER ACCUM:=0, OPERAND :=0, REQ:="? ", 
LGTH, INDX, 



00000 
00000 
00011 
00007 
00007 
00007 
00010 
00010 
00001 
00010 
00016 
00016 
00016 
00016 
00016 
00016 
00016 
00016 
00016 
00016 
00004 
00010 
00010 
00016 
00023 
00026 
00040 
00043 
00043 
00050 
00056 
00057 
00062 
00065 
00070 
00075 
00076 
00076 
00100 
00106 
00116 
00122 
00126 
00133 
00136 




1 
1 
1 

1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
2 
2 
2 
2 
2 
2 



PARMCNT, TYPE; 
INTRINSIC ASCII , BINARY .READ , PRINT , MYCOMMAND , QUIT , WHO ; 
<<END OF DECLARATIONS) > 



PRINT(HEADING,9,0) 
WHO( INTERACTIVE) ; 



LOOP: 



IF INTERACTIVE THEN PRINT(REQ, 1 ,%320) 

LGTH :=READ( INPUT, -72) ; 

IF <> THEN QUIT(l) ; 

IF COMMAND ="END" THEN GO EXIT; 

COMMAND ( LGTH ):*%15; 

TYPE : =MYCOMMAND( COMMAND , , 1 , PARMCNT , 
PARMINFO, TABLE); 
IF < THEN GO ERROR; 
IF PARMCNTol THEN GO ERROR; 
INDX : =PARMINFO-@C0MMAND ; 
OPERAND :=BINARY (COMMAND (INDX) , 

PARMINFO(l). (0:8)) ; 
IF <> THEN GO ERROR; 



CASE (TYPE 

BEGIN 
ACCUM 
ACCUM 
ACCUM 
ACCUM 
ACCUM 

END; 



-1) OF 

=ACCUM+OPERAND 
=ACCUM-0PERAND 
=ACCUM*OPERAND 
=ACCUM/OPERAND 
=0PERAND; 



<<PROGRAM ID>> 
<<LIVE USER?>> 

<<PR0MPT USER>> 
<<GET COMD>> 
<<CHECK FOR ERR>> 
<<DONE - EXIT>> 
<<CARRIAGE RETN>> 

<<TAKE APART CMD>> 

<<NO CMD MATCH>> 
<<NO PARAMETERS>> 
<<SUBSCR OF PARM>> 
<<CONVERT PARM>> 

<<CHECK FOR ERR>> 

<<SELECT OPERATN>> 

<<ADD COMD>> 
<<SUB COMD>> 
<<MUL COMD>> 
<<DIV COMMAND) > 
<<SET COMMAND) > 



Figure 5-2. Using the WHO Intrinsic. (1 of 2) 
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00047000 


00143 


1 


RESULT: 


00048000 


00143 


1 


MOVE ANSWER (8) :=" "; 


00049000 


00155 


1 


ASCII(ACCUM,10,ANSWER(8)) ; 


00050000 


00163 


1 


PRINT(0UTPUT,7,0) ; 


00051000 


00170 


1 


GO LOOP; 


00052000 


00171 


1 


ERROR: 


00053000 


00171 


1 


PRINT(ERRMSG,7,0) ; 


00054000 


00175 


1 


IF NOT INTERACTIVE THEN QUIT(2) 


00055000 


00201 


1 


GO LOOP; 


00056000 


00202 


1 


EXIT: END. 


PRIMARY DB STORAGE=%020 ; SECONDARY DB STORAGE=%00113 


NO. ERRORS=000 


; 


NO. WARNINGS=000 


PROCESSOR TIME 


= 


00:03; ELAPSED TIME=0:00:11 



<<RESET OLD ANSWER>> 
<<CONVERT ACCUM>> 
<<0UTPUT NEW ANSWER>> 
<<CONTINUE CALC>> 

<<ERROR MESSAGE>> 
<<NO LIVE USER-QUIT>> 
<<CONTINUE CALC>> 



Figure 5-2. Using the WHO Intrinsic (2 of 2) 



IDENTIFYING A JOB OR SESSION WITH JOBINFO 

JOB INFO provides the user with three options for identifying a job or session which is on the system. 
The three options are the following: 

• Taking the caller's job/session as default. 

• Specifying a specific job/session number. 

• Specifying a logon ID. 

To retrieve information about the job/session executing JOBINFO, the user must specify the ap- 
propriate jsind (1 for session, 2 for job) and a jsnnn of 0D (double -word zero). Further, the itemnurn 
of the first optional triple must not be a one (1) as this invokes option number three (described 
below). For example, to retrieve the logon ID for the caller, from a session, a JOBINFO call might 
look like this : 

J0BINF0C 1, jsnnn, STATUS, ,, ,1 ,,; snoroe , ERR0R1 ); 
Where: 

• Jsnnn must be OD. 

• Jsind is 1 since JOBINFO is executed from a session, and default to the caller's session for the 
logon ID. 
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• Jsname must be a logical array of 1 3 words. 

• The session number will be returned through jsnnn. 

• The second triple contains the itemnum of 1 . When using the default job or session , the first 
triple can not contain an itemnum equaling 1 . 

It is not possible to attempt a default call with jsind equaling 2 if JOB INFO is executed from a session. 
Likewise, it is not possible to call JOB INFO, attempting a default call, with jsind equaling 1 when 
JOB INFO is executed from a job. 

The user may identify a job or session by specifying the appropriate job/session number through 
jsnnn, along with the appropriate jsind. By supplying a non-zero jsnnn, the other two job/session 
identification options are over-ridden. There is no restriction on the use of any of the optional 
triples, or itemnums. An example of specifying a specific job/session number is a follows: 

JOBINFOC 2, jsnnn, STATUS, 1, jsname, ERR0R1 ); 

Where: 

• Jsind equals 2 and specifies that jsnnn is a job number. 

• Jsnnn is a job number. 

• Itemnum equals 1 denoting that the logon ID of job number jsnnn is to be retrieved. 

The user may identify a job or session by specifying the appropriate job/session by supplying the ap- 
propriate logon ID through the first optional triple. The user must supply the appropriate jsind and 
jsnnn must be OD. The logon ID is specified through the first triple with itemnum equal to 1 , and 
item being a logical array containing the logon ID (a character string). The logon ID must be ter- 
minated by a binary zero (0). The maximum length of the logon ID is twenty-six (26) characters, 
plus one ( 1 ) for the binary zero terminator. An example of this is as follows : 

JOBINFOC 2, jsnnn, STATUS, 1, LOGON 'ID, ERR0R1 ); 

Where: 

• Jsind equals 2, denoting the LOGON 'ID supplied is that of a job. 

• Jsnnn equals OD. 

• The job number of the job denoted by LOGON ' ID will be returned through jsnnn . 

• The first triple is specified with an itemnum equal to 1 , a logical array LOGON 'ID containing the 
logon id of a job (terminated by a binary 0) , and an integer error return for the item. 

An example of initializing LOGON 'ID might be as follows: 

MOVE LOGON'IDCO) := "TEST JOB, LARRY. OSE",0; 
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CONVERTING NUMBERS FROM BINARY CODE TO ASCII STRINGS 



You can convert a one-word binary number to an octal or decimal number represented as an ASCII 
string with the ASCII intrinsic. The length of the resulting ASCII string can be returned as an in- 
teger value. BINARY will not convert numbers which are greater than 32,767 in value. 

The ASCI I intrinsic call is illustrated in Figure 5-3, statement 00049000: 

ASCIICACCUM,10,ANSWERC8)); 

converts the one-word binary number contained in ACCUM to the base 10 and places the converted 
value into the ninth element (0 is the first element) of the byte array ANSWER. The length of the 
resulting ASCII string is unimportant in this application , and therefore no variable is provided in the 
intrinsic call for this return. If the length were desired, the intrinsic call could have had the form: 

LGTH := ASC IK ACCUM, 10, ANSWER C8»; 

The DASCII intrinsic, which converts a double-word (32-bit) binary number to an octal or decimal 
number represented as an ASCII string, is shown in statement 00015000 in Figure 5-4. 

LGTH : =DASC 1 1 CCNTR ,10, BMSGC20 ) ) ; 

converts the 32-bit binary number contained in CNTR to the base 10 and places the converted decimal 
value starting with the 21st element of byte array BMSG. The length (number of characters) of the 
converted value is returned to LGTH. 

The value is converted from binary to ASCII so that it can be printed by the PR I NT statement. 
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PAGE 0001 


HEV 


III 


00001000 


00000 





00002000 


00000 





00003000 


00000 


1 


00004000 


00011 


1 


00005000 


00007 


1 


00006000 


00007 


1 


00007000 


00007 


1 


00008000 


00010 


1 


00009000 


00010 


1 


00010000 


00001 


1 


00011000 


00010 


1 


00012000 


00016 


1 


00013000 


00016 


1 


00014000 


00016 


1 


00015000 


00016 


1 


00016000 


00016 


1 


00017000 


00016 


1 


00018000 


00016 


1 


00019000 


00016 


1 


00020000 


00016 


1 


00021000 


00016 


1 


00022000 


00004 


1 


00023000 


00010 


1 


00024000 


00010 


1 


00025000 


00016 


1 


00026000 


00023 


1 


00027000 


00026 


1 


00028000 


00040 


1 


00029000 


00043 


1 


00030000 


00043 


1 


00031000 


00050 


1 


00032000 


00056 


1 


00033000 


00057 


1 


00034000 


00062 


1 


00035000 


00065 


1 


00036000 


00070 


1 


00037000 


00075 


1 


00038000 


00076 


1 


00039000 


00076 


1 


00040000 


00100 


1 


00041000 


0106 


2 


00042000 


00116 


2 


00043000 


00122 


2 


00044000 


00126 


2 


00045000 


00133 


2 


00046000 


00136 


2 



HEWLETT-PACKARD 32100A.08.1 
$C0NTR0L USLINIT 
BEGIN 



SPL[4W] TUE, OCT 28, 1982, 4:35 PM 



ARRAY HEADING(0:8) :="INTEGER CALCULATOR 

ARRAY ERRMSG(0:6) :="ILLEGAL ENTRY."; 

ARRAY INPUT(0:36); 

BYTE ARRAY COMMAND (*) =INPUT ; 

BYTE ARRAY ANSWER (0 : 13) : ="ACCUM = 

ARRAY OUTPUT(*)=ANSWER; 

BYTE ARRAY TABLE(0 : 25) : = 

5, 3, "ADD", 5,3, "SUB 

5,3, "DIV", 5,3,"SET 
INTEGER ARRAY PARMINF0(0 : 1) ; 
LOGICAL INTERACTIVE :=FALSE; 
INTEGER ACCUM:=0, OPERAND : =0 
LGTH, INDX, 



5.3, 
0; 



REQ:="? 
PARMCNT, 



"MUL" , 



TYPE; 
INTRINSIC ASCII , BINARY .READ , PRINT , MYCOMMAND , QUIT , WHO ; 



<<END OF DECLARATIONS>> 

PRINT(HEADING,9,0) ; 
WH0( INTERACTIVE); 
LOOP: 

IF INTERACTIVE THEN PRINK REQ , 1 ,%320) 

LGTH:=READ(INPUT,-72) ; 

IF <> THEN QUIT(l) ; 

IF COMMAND ="END" THEN GO EXIT; 

COMMAND ( LGTH ):=%15; 

TYPE : =MYCOMMAND( COMMAND , , 1 . PARMCNT . 
PARMINFO, TABLE) ; 
IF < THEN GO ERROR; 
IF PARMCNTol THEN GO ERROR; 
INDX : =PARMINFO-@COMMAND ; 
OPERAND : =BINARY (COMMAND ( INDX ) , 

PARMINFO(l). (0:8)) ; 
IF <> THEN GO ERROR; 



CASE (TYPE 


-1) OF 


BEGIN 




ACCUM 


=ACCUM+OPERAND 


ACCUM 


"ACCUM-OPERAND 


ACCUM 


=ACCUM*OPERAND 


ACCUM 


=ACCUM/OPERAND 


ACCUM 


"OPERAND; 


END; 





<< PROGRAM ID>> 
<<LIVE USER?>> 

<<PR0MPT USER>> 
<<GET C0MD>> 
<<CHECK FOR ERR>> 
«DONE - EXIT>> 
<<CARRIAGE RETN>> 

<<TAKE APART CMD>> 

<<NO CMD MATCH >> 
<<NO PARAMETERS>> 
<<SUBSCR OF PARM>> 
<<C0NVERT PARM>> 

<<CHECK FOR ERR>> 

<<SELECT OPERATN>> 



<<ADD 
<<SUB 
<<MUL 
<<DIV 
<<SET 



C0MD>> 
COMD>> 
C0MD>> 
COMMAND >> 
COMMAND >> 



Figure 5-3. Using the ASCII Intrinsic. (1 of 2) 
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00047000 


00143 


1 


RESULT: 




00048000 


00143 


1 


MOVE ANSWER (8) :=" " ; 


<<RESET OLD ANSWER>> 


00049000 


00155 


1 


ASCII(ACCUM,10,ANSWER(8)) ; 


<<CONVERT ACCUM>> 


00050000 


00163 


1 


PRINT(OUTPUT,7,0) ; 


<<0UTPUT NEW ANSWER>> 


00051000 


00170 


1 


GO LOOP; 


<<CONTINUE CALC>> 


00052000 


00171 


1 


ERROR: 




00053000 


00171 


1 


PRINT(ERRMSG,7,0); 


<<ERROR MESSAGE>> 


00054000 


00175 


1 


IF NOT INTERACTIVE THEN QUIT(2); 


<<NO LIVE USER-QUIT>> 


00055000 


00201 


1 


GO LOOP; 


<<CONTINUE CALC>> 


00056000 


00202 


1 


EXIT: END. 




PRIMARY 


DB ST0RAGE=%020; SECONDARY DB STORAGE=%00113 




NO. ERR0RS=00C 


; 


NO. WARNINGS=000 




PROCESSOR TIME=0 


00:03; ELAPSED TIME=0:00:11 





Figure 5-3. Using the ASCII Intrinsic (2 of 2) 
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PAGE 0001 HEWLETT-PACKARD 32100A.08.1 SPL[4W] TUE , OCT 28, 1982, 4:35 
00001000 00000 $C0NTR0L USLINIT 
BEGIN 

ARRAY HEADING(0:10):="C0NTR0L Y TRAP EXAMPLE"; 

ARRAY MSG(0:15) :="C0UNTER CURRENTLY = " ; 

BYTE ARRAY BMSG(*) =MSG ; 

DOUBLE CNTR:=0D; 

INTEGER DUMMY, LGTH; 



00002000 00000 
00003000 00000 
00004000 00013 
00005000 00020 
00006000 00020 
00007000 00020 
00008000 00020 
00009000 00020 
00010000 00020 
00011000 00020 
00012000 00000 
00013000 00000 
00014000 00000 
00015000 00000 
00016000 00007 
00017000 00013 
00018000 00014 
00019000 00016 



00020000 
00021000 
00022000 
00023000 
00024000 
00025000 
00026000 



00017 
00000 
00000 
00000 
00000 
00004 
00007 



00027000 00012 
00028000 00012 
00029000 00023 
00030000 00027 1 END. 

PRIMARY DB STORAGE=%007 

NO. ERRORS=000; 

PROCESSOR TIME=0:00:02; 



INTRINSIC PRINT, XCONTRAP, QUIT, DASCII .RESETCONTROL ; 

PROCEDURE CONTROLY; 
BEGIN 

INTEGER SDEC=Q+1; 



10,BMSG(20)) 



LGTH:=DASCII(CNTR, 
PRINT(MSG,16,0); 
RESETCONTROL; 
TOS:=%31400+SDEC; 
ASSEMBLE (XEQ 0); 
END; 



<<END OF DECLARATIONS>> 

PRINT(HEADING,H,0) ; 
XCONTRAP ( @C0NTROLY , DUMMY ) 
IF < THEN QUIT(l) ; 



<<CONVERT COUNTER) > 
<<OUTPUT COUNTER>> 
<<REARM CNTL Y TRAP>> 
<<BUILD EXIT INSTRN>> 
<<EXECUTE EXIT 



LOOP: 



CNTR:=CNTR+1D; 
IF CNTRO000000D 



THEN GO LOOP; 



<<PROGRAM ID>> 
<<ARM CNTL Y TRAP>> 
<<CHECK FOR ERROR>> 

<<DOUBLE INCREMENT>> 
<<CONTINUOUS LOOP>> 



SECONDARY DB ST0RAGE=%00033 
NO. WARNINGS=000 
ELAPSED TIME=0:00:26 



Figure 5-4. Using the DASCII Intrinsic 
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CONVERTING NUMBERS FROM AN ASCII NUMERIC STRING TO 
A BINARY CODED VALUE 

The BINARY intrinsic converts an ASCII numeric string to its equivalent binary value. The converted 
value is returned to the calling program. 

The BINARY intrinsic call is illustrated in Figure 5-5, statement 00035000: 

OPERAND: =BINARYCC0MMAND(INDX),PARMINF0(1 ). CO :8)>; 

converts the ASCII numeric string contained in the element specified by INDX of the array COMMAND 
to its binary equivalent. The length of the ASCII string is specified by the first eight bits of the first 
word of the array PARMINF0. The resulting binary value is stored in the word OPERAND. 

To convert a number from an ASCII string to a double-word (32-bit) binary value, the DBINARY in- 
trinsic is used. 

A DBINARY intrinsic call could be of the form: 

DVAL : =DBINARY(STRING, LENGTH) ; 

where STRING contains the octal or decimal number to be converted and LENGTH is an integer 
representing the length of the string containing the ASCII -coded value. The converted double -word 
value is returned to DVAL. 
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PAGE 0001 HEWLETT-PACKARD 32100A. 08.1 SPL[4W] TUE 


OCT 


28, 1982, 4:35 PM 


00001000 


00000 





SCONTROL USLINIT 






00002000 


00000 





BEGIN 






00003000 


00000 


1 


ARRAY HEADING(0:8) :="INTEGER CALCULATOR 


I , 


00004000 


00011 


1 


ARRAY ERRMSG(0:6):="ILLEGAL ENTRY. 






00005000 


00007 


1 


ARRAY INPUT{0:36); 






00006000 


00007 


1 


BYTE ARRAY C0MMAND(*) =INPUT ; 






00007000 


00007 


1 


BYTE ARRAY ANSWER (0 : 13 ) : ="ACCUM = 


„ 




00008000 


00010 


1 


ARRAY OUTPUT(*)=ANSWER; 






00009000 


00010 


1 


BYTE ARRAY TABLE (0 :25 ): = 






000100OO 


00001 


1 


5,3,"ADD" , 5,3, "SUB", 


5,3, 


■MUL", 


00011000 


00010 


1 


5,3,"DIV". 5,3, "SET", 


0; 




00012000 


00016 


1 


INTEGER ARRAY PARMINFO(0 : 1 ) ; 






00013000 


00016 


1 


LOGICAL INTERACTIVE :=FALSE; 






00014000 


00016 


1 


INTEGER ACCUM :=0, OPERAND :=0, REQ: 


_ II O II 


i 


00015000 


00016 


1 


LGTH, INDX, PARMCNT, 


TYPE; 


00016000 


00016 


1 








00017000 


00016 


1 


INTRINSIC ASCII , BINARY .READ , PR INT , 


MYCOMMAND, QUIT, WHO; 


00018000 


00016 


1 








00019000 


00016 


1 


<<END OF DECLARATIONS>> 






00020000 


00016 


1 








00021000 


00016 


1 


PRINT(HEADING,9,0); 




<<PR0GRAM ID>> 


00022000 


00004 


1 


WHO(INTERACTIVE) ; 




<<LIVE USER?>> 


00023000 


00010 


1 


LOOP: 






00024000 


00010 


1 


IF INTERACTIVE THEN PRINT(REQ, 


1,%320) ;<<PR0MPT USER>> 


00025000 


00016 


1 


LGTH :=READ( INPUT, -72) ; 




<<GET C0MD>> 


00026000 


00023 


1 


IF <> THEN QUIT(l) ; 




<<CHECK FOR ERR>> 


00027000 


00026 


1 


IF COMMAND ="END" THEN GO EXIT 




<<DONE - EXIT>> 


00028000 


00040 


1 


COMMAND ( LGTH ):=%15; 




<<CARRIAGE RETN>> 


00029000 


00043 


1 








00030000 


00043 


1 


TYPE : =MYCOMMAND( COMMAND , , 1 , PARMCNT 


<<TAKE APART CMD>> 


00031000 


00050 


1 


PARMINFO, TABLE) ; 




00032000 


00056 


1 


IF < THEN GO ERROR; 




<<N0 CMD MATCH>> 


00033000 


00057 


1 


IF PARMCNTol THEN GO ERROR; 




<<NO PARAMETERS>> 


00034000 


00O62 


1 


INDX : =PARMINF0-@C0MMAND ; 




<<SUBSCR OF PARM>> 


00035000 


00065 


1 


OPERAND: =BINARY(COMMAND( INDX) , 




<<C0NVERT PARM>> 


00036000 


00070 


1 


PARMINFO (1).(0 


:8)); 




00037000 


00075 


1 


IF <> THEN GO ERROR; 




<<CHECK FOR ERR>> 


00038000 


00076 


1 








'00039000 


00076 


1 


CASE (TYPE-1) OF 




<<SELECT 0PERATN>> 


00040000 


00100 


1 


BEGIN 






00041000 


00106 


2 


ACCUM 


=ACCUM+OPERAND 






<<ADD C0MD>> 


00042000 


00116 


2 


ACCUM 


-ACCUM-OPERAND 






<<SUB C0MD>> 


00043000 


00122 


2 


ACCUM 


=ACCUM*OPERAND 






<<MUL C0MD>> 


00044000 


00126 


2 


ACCUM 


=ACCUM/OPERAND 






<<DIV C0MMAND>> 


00045000 


00133 


2 


ACCUM 


=0PERAND; 




<<SET C0MMAND>> 


00046000 


00136 


2 


END; 







Figure 5-5. Using the BINARY Intrinsic. (1 of 2) 
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00047000 


00143 


1 


RESULT: 




00048000 


00143 


1 


MOVE ANSWER (8) :=" " ; 


<<RESET OLD ANSWER>> 


00049000 


00155 


1 


ASCII(ACCUM,10,ANSWER(8)) ; 


<<C0NVERT ACCUM>> 


00050000 


00163 


1 


PRINT(0UTPUT,7,0) ; 


<<OUTPUT NEW ANSWER>> 


00051000 


00170 


1 


GO LOOP; 


<<C0NTINUE CALC>> 


00052000 


00171 


1 


ERROR: 




00053000 


00171 


1 


PRINT(ERRMSG,7,0) ; 


<<ERR0R MESSAGE>> 


00054000 


00175 


1 


IF NOT INTERACTIVE THEN QUIT(2); 


<<N0 LIVE USER-QUIT>> 


00055000 


00201 


1 


GO LOOP; 


<<CONTINUE CALC>> 


00056000 


00202 


1 


EXIT: END. 




PRIMARY 


DB STORAGE=%020; SECONDARY DB STORAGE=%00113 




NO. ERR0RS=000; 


NO. WARNINGS=000 




PROCESSOR TIME=0 


00:03; ELAPSED TIME=0:00:11 





Figure 5-5. Using the BINARY Intrinsic (2 of 2) 

TRANSLATING CHARACTERS WITH THE CTRANSLATE INTRINSIC 

The CTRANSLATE intrinsic is used for character code translating , whether between the standard com- 
puter character codes, or a user-defined code. It permits you to obtain character code conversions 
within programs of your own design. In the code parameter of CTRANSLATE, the following values 
specify the translation table to be used : 

The user -supplied table specified in the table parameter. 

1 EBCDIC to ASCII. 

2 ASCII to EBCDIC. 

3 Reserved for future use. 

4 Reserved for future use. 

5 EBCDIK to JIS (Katakana data). 

6 JIS to EBCDIK. 

As an example of converting from EBCDIC to ASCII, suppose the byte array ESTRING contains the 
EBCDIC characters " JOB 2" . To convert this string to its ASCII equivalent and store it in the byte 
array ASTR I NG use the following intrinsic call ; 

CTRANSLATE ( 1 , ESTR I NG , ASTR I NG , 5 ) ; 
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The parameters specified in the previous intrinsic call are : 

code 1, which specifies the EBCDIC-to- ASCII table. An Ofor this parameter 

specifies a user-defined translation table, and a 2 specifies the ASCII-to- 
EBCDIC table. 

instring ESTRING, a byte array containing the string to be converted. 

outstring ASTRING, a byte array which will contain the ASCII characters for 

" JDB 2" when the intrinsic is executed. 

stringlength 5, which specifies the length , in bytes , of the string " JDB 2" . 

table Omitted. This parameter, if specified , consists of a byte array containing a 

user-defined table to be used in the translation. 



TRANSMITTING PROGRAM INPUT/OUTPUT FROM JOB/SESSION 
INPUT/OUTPUT DEVICES 

In addition to the FREADand FWRITE intrinsics, MPE provides other intrinsics that allow you to read 
information from the job/session input device (READ and READX) or write information to the job/ses- 
sion list device (PRINT). You can transmit a message to the System Console with the PRINTDP intrin- 
sic or transmit a message to the System Console and solicit a reply with the PR I NTOPREPLY intrinsic. 



NOTE 



The READ, READX, and PRINT intrinsics are limited in 
their usefulness in that :FILE commands are not al- 
lowed. Also, the filenum parameter, obtained from the 
FOPEN intrinsic, is not available for use with these in- 
trinsics. Therefore, if an error occurs, it is not possible 
to determine what it is because the FCHECK intrinsic 
requires the filenum parameter. You may find it more 
convenient (and a better programming practice) to use 
the FOPEN intrinsic to open the files $STDIN and 
SSTDLIST, then issue FREADand FWRITE against these 
files. 

Reading Input from the Job/Session Input Device 

The job/session input device is the source of all MPE commands relating to a job or session , and is the 
primary source of all ASCII information input to the job or session. You can read a string of ASCII 
characters from the job/session input device into an array in your program with the READ and READX 
intrinsics. The READ and READX intrinsics are identical, except that the READX intrinsic reads input 
from SSTDINX instead of $STDIN. SSTDINX is equivalent to $STDINexcept that records with a colon 
(:) in column 1 indicate the end -of -file to $STDIN, and only the commands :EDD, and :EDF indicate 
the end of file for SSTDINX. The READ intrinsic call is illustrated in Figure 5-6. 
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PAGE 000] 


1 HEWLETT-PACKARD 32100A.08.1 SPL[4W] TUE , OCT 


28, 1982, 4:35 PM 


00001000 


00000 





SC0NTR0L USLINIT 




00002000 


00000 





BEGIN 




00003000 


00000 


1 


ARRAY HEADING(0: 8): '"INTEGER CALCULATOR' 




00004000 


00011 


1 


ARRAY ERRMSG{0:6) :="ILLEGAL ENTRY."; 




00005000 


00007 


1 


ARRAY INPUT(0:36) ; 




00006000 


00007 


1 


BYTE ARRAY COMMAND!*) =INPUT ; 




00007000 


00007 


1 


BYTE ARRAY ANSWER (0 : 13 ): ="ACCUM = 




00008000 


00010 


1 


ARRAY OUTPUT(*)=ANSWER; 




00009000 


00010 


1 


BYTE ARRAY TABLE(0:25) := 




00010000 


00001 


1 


5, 3, "ADD", 5,3, "SUB", 5,3,' 


MUL", 


00011000 


00010 


1 


5,3,"DIV", 5,3, "SET", 0; 




00012000 


00016 


1 


INTEGER ARRAY PARMINF0(0 : 1 ) ; 




00013000 


00016 


1 


LOGICAL INTERACTIVE :=FALSE; 




00014000 


00016 


1 


INTEGER ACCUM:=0, OPERAND : =0 , REQ:="? " 




00015000 


00016 


1 


LGTH, INDX, PARMCNT, 


TYPE; 


00016000 


00016 


1 






00017000 


00016 


1 


INTRINSIC ASCII , BINARY , READ , PRINT .MYCOMMAND ,QUIT ,WH0 ; 


00018000 


00016 


1 






00019000 


00016 


1 


<<END OF DECLARATIONS) > 




00020000 


00016 


1 






00021000 


00016 


1 


PRINT(HEADING,9,0) ; 


<<PROGRAM ID>> 


00022000 


00004 


1 


WHO( INTERACTIVE) ; 


<<LIVE USER?>> 


00023000 


00010 


1 


LOOP: 




00024000 


00010 


1 


IF INTERACTIVE THEN PRINT(REQ, 1 ,%320 ) ; <<PROMPT USER>> 


00025000 


00016 


1 


LGTH:=READ(INPUT,-72) ; 


<<GET C0MD>> 


00026000 


00023 


1 


IF <> THEN QUIT(l) ; 


<<CHECK FOR ERR>> 


00027000 


00026 


1 


IF COMMAND ="END" THEN GO EXIT; 


<<DONE - EXIT>> 


00028000 


00040 


1 


COMMAND ( LGTH ):=%15; 


<<CARRIAGE RETN>> 


00029000 


00043 


1 






00030000 


00043 


1 


TYPE : =MYCOMMAND (COMMAND , , 1 , PARMCNT 


<<TAKE APART CMD>> 


00031000 


00050 


1 


PARMINFO, TABLE); 




00032000 


00056 


1 


IF < THEN GO ERROR; 


<<NO CMD MATCH>> 


00033000 


00057 


1 


IF PARMCNTol THEN GO ERROR; 


<<NO PARAMETERS>> 


00034000 


00062 


1 


INDX : =PARMINFO-@COMMAND ; 


<<SUBSCR OF PARM>> 


00035000 


00065 


1 


OPERAND —BINARY (COMMAND (INDX) , 


<<CONVERT PARM>> 


00036000 


00070 


1 


PARMINFO(l). (0:8)) ; 




00037000 


00075 


1 


IF <> THEN GO ERROR; 


<<CHECK FOR ERR>> 


00038000 


00076 


1 






00039000 


00076 


1 


CASE (TYPE-1) OF 


<<SELECT 0PERATN>> 


00040000 


00100 


1 


BEGIN 




00041000 


00106 


2 


ACCUM 


=ACCUM+OPERAND 




<<ADD C0MD>> 


00042000 


00116 


2 


ACCUM 


=ACCUM-OPERAND 




<<SUB C0MD>> 


00043000 


00122 


2 


ACCUM 


=ACCUM*OPERAND 




<<MUL COMD>> 


00044000 


00126 


2 


ACCUM 


=ACCUM/OPERAND 




<<DIV COMMAND>> 


00045000 


00133 


2 


ACCUM 


=0PERAND; 


<<SET C0MMAND>> 


00046000 


00136 


2 


END; 





Figure 5-6. Using the PRINT and READ Intrinsics (1 of 2) 
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00047000 


00143 


1 


RESULT: 




00048000 


00143 


1 


MOVE ANSWER(8):=" "; 


<<RESET OLD ANSWER>> 


00049000 


00155 


1 


ASCII (ACCUM, 10, ANSWER (8) ); 


<<C0NVERT ACCUM>> 


00050000 


00163 


1 


PRINT(0UTPUT,7,0); 


<<0UTPUT NEW ANSWER>> 


00051000 


00170 


1 


GO LOOP; 


<<C0NTINUE CALC>> 


00052000 


00171 


1 


ERROR: 




00053000 


00171 


1 


PRINT(ERRMSG,7,0); 


<<ERR0R MESSAGE >> 


00054000 


00175 


1 


IF NOT INTERACTIVE THEN QUIT (2); 


<<N0 LIVE USER-QUIT>> 


00055000 


00201 


1 


GO LOOP; 


<<C0NTINUE CALC>> 


00056000 


00202 


1 


EXIT: END. 




PRIMARY 


DB ST0RAGE=%020; SECONDARY DB STORAGE=%00113 




NO. ERRORS=000; 


NO. WARNINGS=000 




PROCESSOR TIME=0 


00:03; ELAPSED TIME=0:00:11 





Figure 5-6. Using the PRINT and READ Intrinsics (2 of 2) 

Statement 00025000: 

LGTH:=READC INPUT, -72); 

reads an entry from the terminal and transfers this string to the array INPUT. The maximum length 
of the string to be read is specified as 72 bytes (-72). The actual number of bytes read is returned 
and stored in the word LGTHwhen the intrinsic executes. 

Statement 00026000: 

IF <> THEN QUITCD; 

checks for a CCG or CCL condition code and, if either is found the QUIT intrinsic is executed and the 
process is aborted. The (1) parameter is an arbitrary user -supplied value that is displayed as part of 
the abort message. 

Writing Output to the Job/Session List Device 

Normally, the list device for jobs is a line printer and for sessions a terminal. You can write a string 
of ASCII characters from an array in your program to this list device with the PRINT intrinsic. 

In Figure 5-6, statement 00021000: 

PRINTCHEADING,9,0); 

transmits the string "INTEGER CALCULATOR" from the array HEADING (refer to statement 
00003000). The length parameter is specified as 9, which means that the string to be transmitted is 9 
words long (a negative value would specify bytes). The control parameter is 0, signifying that the full 
record is to be printed , up to 132 characters per line , using single spacing . 
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Writing Output to the System Console 

The PRINTOP intrinsic could be called as follows: 

PR I NTQP CMESS AGE , 1 , ) ; 

The character string to be transmitted is contained in the array MESSAGE. The parameter 1 signifies 
that the message is 10 words long (a negative value would specify bytes). If zero is specified for the 
length parameter, only the standard message prefix is written on the System Console; the string con- 
tained in MESSAGE would not be transmitted. 

Writing Output to the System Console and Requesting a Reply 

The PRINTQPREPLY intrinsic can be used to transmit an ASCII string from an array in your program 
to the System Console and to request that a reply be returned. For example, a program could ask the 
System Operator if the line printer contains a certain type of form . If the response is affirmative , the 
program could then write information on these forms. 

A PRINTOPREPLY intrinsic call could be as follows: 

REPLGTH : =PR I NTDPREPLY (MESSAGE ,18,0, REPLY , - 3) ; 

The following parameters were specified in the above call : 

message An ASCII string contained in the array MESSAGE. 

length 18 words. A negative value would specify bytes. If zero is specified for 

the length parameter, only the standard message prefix is written on the 
System Console ; the string contained in MESSAGE would not be transmitted . 

control (MPE ignores this parameter). 

reply The System Operator's reply will be returned to the array REPLY. 

expected! -3, signifying that the maximum expected length of the reply is 3 bytes. A 

positive value would specify words. 

The actual length of the System Operator's reply is returned to REPLGTH. This is a positive value 
representing a byte count in this case because expectedl is negative (-3). If expectedl is positive, then 
the length returned represents words. The maximum value for expectedl is 31 bytes. 



SUSPENDING THE CALLING PROCESS 



The calling process can be suspended with the PAUSE intrinsic. The maximum interval allowed is ap- 
proximately 2,147,484 seconds (almost 25 days). A PAUSE intrinsic call could be as shown below, 
where INT is a real variable that specifies the amount of time, in seconds, that the process is 
suspended : 

PAUSE CI NT); 
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When I NT seconds have elapsed , control is returned to the calling process and execution resumes at 
the statement following the PAUSE intrinsic call. 



REQUESTING A PROCESS BREAK 



During a session, you can initiate a break programmatically with the CAUSEBREAK intrinsic. The 
CAUSEBREAK intrinsic is the programmatic equivalent of using the [break! key in a session. It allows 
you to enter certain MPE commands to perform functions such as creating a file or transmitting an 
informal message. The MPE commands permitted during a break are listed below: 



ABORT 


HELP 


: RENAME 


: SHOW IN 


ALTSEC 


IF 


: REPORT 


SHDWJCW 


ALTVSET 


LISTEQ 


: RESET 


SHOWJOB 


BUILD 


LISTF 


:RESETDUMP 


SHOWME 


COMMENT 


LISTFTEMP 


RESUME 


SHOWOUT 


DEBUG 


LISTVS 


SAVE 


SHOWTIME 


DISCRPS 


MOUNT 


SECURE 


SPEED 


DISMOUNT 


NEWVSET 


SETCATALOG 


STARTSESS 


DSLINE 


PTAPE 


SETDUMP 


STREAM 


DSTAT 


PURGE 


SETJCW 


TELL 


ELSE 


REDO 


SETMSG 


TELLOP 


ENDIF 


RELEASE 


SHOWCACHE 


VSUSER 


FILE 


REMOTE 


SHOWCATALOG 




GETRIN 


REMOTE HELLO 


SHOWDEV 





(Refer to the MPE V Commands Reference Manual (32033-90006) for discussions of the above 
commands.) 

The CAUSEBREAK intrinsic is not valid in a job. A program containing the CAUSEBREAK intrinsic will 
not break if it is executed from a UDC which specifies the NOBREAK option. 

The form of the CAUSEBREAK intrinsic call is: 

CAUSEBREAK; 
Execution of the process can be resumed where the interruption occurred by entering the command : 

; RESUME 

TERMINATING A PROCESS 



You can programmatically terminate a process with the TERMINATE intrinsic. The process and all of 
its descendants, including any extra data segments belonging to them, are deleted. 
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All files still open by the process are closed with a disposition of 0. (For more details, refer to the 
FCLOSE intrinsic discussion in Section II.) 

The form of the TERM I NATE intrinsic call is: 

TERMINATE; 

ABORTING A PROCESS 



If called from within any process in a user-process structure, the QUIT intrinsic aborts that process. 
All process files still open are closed with a disposition of 0. (Refer to the FCLDSE intrinsic discussion 
in Section II for more details.) 

The QUIT intrinsic transmits an abort mesage to the calling process calling device and terminates the 
process in an error state. (Refer to "Run -Time Messages" in Appendix A.) In a session, the process is 
aborted but the session remains active when the entire program finishes. In a batch job, the job ter- 
minates when the entire program finishes unless the : CONTINUE command is in effect. (Refer to the 
MPE V Commands Reference Manual (32033-90006) for more information on the :C0NTINUE 
command.) 

Figure 5-7 shows the QUIT intrinsic being called if a READ statement did not execute properly. The 
abort message resulting from the QU I T intrinsic is shown below: 

ABORT '.program. group . account%0 . X26 
PROGRAM ERROR #18 : PROCESS QUIT . PARAM=1 

Statement 00026000: 

IF <> THEN QUITC1); 

checks for a CCG or CCL condition code and, if one is returned, the QUIT intrinsic is called. The 
abort message is printed and the process is aborted. The QUIT parameter (1) is an arbitrary number 
supplied by the user and can be used to identify a specific QUIT intrinsic call in case of multiple pos- 
sible QUIT intrinsic calls. This number, 1 in this case, is printed at the end of the abort message 
(PARAM=1). The system Job Control Word, JCW, is set to the value %1 00000, with the QUIT pa- 
rameter as a modifier. In this example, JCW would be set to %1 00001 . 



ABORTING A PROGRAM 



You can programmatically abort the entire user-process structure (program) with the QUITPROG in- 
trinsic. This intrinsic destroys all processes up to, but not including, the job/session main process. 
All files still open by any user process are closed with a disposition of 0. (Further details can be found 
under the FCLOSE intrinsic in Section II.) 
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PAGE 0001 


HP32100A.08.01 [4W] 


(C) HEWLETT-PACKARD COMPANY 


00001000 


00000 





SCONTR0L USLINIT 


00002000 


00000 





BEGIN 


00003000 


00000 


1 


ARRAY HEADING(0:8):="INTEGER CALCULATOR"; 


00004000 


00011 


1 


ARRAY ERRMSG(0:6):="ILLEGAL ENTRY."; 


00005000 


00007 


1 


ARRAY INPUT(0:36); 


00006000 


00007 


1 


BYTE ARRAY COMMAND (*) "INPUT ; 


00007000 


00007 


1 


BYTE ARRAY ANSWER (0 : 13 ): ="ACCUM = "; 


00008000 


00010 


1 


ARRAY OUTPUT(*)=ANSWER; 


00009000 


00010 


1 


BYTE ARRAY TABLE (0 :25 ): = 


00010000 


00001 


1 


5 ,3," ADD", 5,3,"SUB" , 5,3,"MU 


00011000 


00010 


1 


5,3, "DIV", S^/'SET", 0; 


00012000 


00016 


1 


INTEGER ARRAY PARMINFO(0 : 1) ; 


00013000 


00016 


1 


LOGICAL INTERACTIVE :=FALSE; 


00014000 


00016 


1 


INTEGER ACCUM:=0, OPERAND: =0, REQ:="? ", 


00015000 


00016 


1 


LGTH, INDX, PARMCNT, 


00016000 


00016 


1 




00017000 


00016 


1 


INTRINSIC ASCII , BINARY , READ , PRINT .MYCOMMAN 


00018000 


00016 


1 




00019000 


00016 


1 


<<END OF DECLARATIONS) > 


00020000 


00016 


1 




00021000 


00016 


1 


PRINT(HEADING,9,0); 


00022000 


00004 


1 


WHO (INTERACTIVE); 


00023000 


00010 


1 


LOOP: 


00024000 


00010 


1 


IF INTERACTIVE THEN PRINT(REQ , 1 ,%320) ; 


00025000 


00016 


1 


LGTH: =READ( INPUT, -72); 


00026000 


00023 


1 


IF <> THEN QUIT(l); 


00027000 


00026 


1 


IF COMMAND ="END" THEN GO EXIT; 


00028000 


00040 


1 


COMMAND! LGTH ):=%15; 


00029000 


00043 


1 




00030000 


00043 


1 


TYPE : =MYCOMMAND (COMMAND , , 1 , PARMCNT , 


00031000 


00050 


1 


PARMINFO, TABLE) ; 


00032000 


00056 


1 


IF < THEN GO ERROR; 


00033000 


00057 


1 


IF PARMCNTol THEN GO ERROR; 


00034000 


00062 


1 


INDX:=PARMINFO-@COMMAND; 


00035000 


00065 


1 


OPERAND :=BINARY( COMMAND ( INDX), 


00036000 


00070 


1 


PARMINFO(l). (0:8)); 


00037000 


00075 


1 


IF <> THEN GO ERROR; 


00038000 


00076 


1 




00037000 


00076 


1 


CASE (TYPE-1) OF 


00040000 


00100 


1 


BEGIN 


00041000 


00106 


2 


ACCUM 


=ACCUM+OPERAND 




00042000 


00116 


2 


ACCUM 


=ACCUM-OPERAND 




00043000 


00122 


2 


ACCUM 


=ACCUM*OPERAND 




00044000 


00126 


2 


ACCUM 


=ACCUM/OPERAND 




00045000 


00133 


2 


ACCUM 


=OPERAND; 


00046000 


00136 


2 


END; 







1980 



TYPE; 



<<PROGRAM ID>> 
<<LIVE USER?>> 

<<PR0MPT USER?>> 
<<GET C0MD>> 
<<CHECK FOR ERR>> 
<<DONE - EXIT>> 
<<CARRIAGE RETN>> 

<<TAKE APART CMD>> 

<<N0 CMD MATCH>> 
<<N0 PARAMETERS>> 
<<SUBSCR OF PARM>> 
<<C0NVERT PARM>> 

<<CHECK FOR ERR>> 

<<SELECT 0PERATN>> 



<<ADD 
<<SUB 
<<MUL 
<<DIV 
<<SET 



C0MD>> 
COMD>> 
COMD>> 
COMD>> 
COMD>> 



Figure 5-7. Using the QUIT Intrinsic. (1 of 2) 
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00047000 


00143 


1 


RESULT: 




00048000 


00143 


1 


MOVE ANSWER(8) :=" " ; 


<<RESET OLD ANSWER>> 


00049000 


00155 


1 


ASCII(ACCUM,10,ANSWER(8) ) ; 


<<CONVERT ACCUM>> 


00050000 


00163 


1 


PRINT(OUTPUT,7,0); 


<<0UTPUT NEW ANSWER >> 


00051000 


00170 


1 


GO LOOP; 


<<CONTINUE CALC>> 


00052000 


00171 


1 


ERROR: 




00053000 


00171 


1 


PRINT(ERRMSG,7,0); 


<<ERROR MESSAGE>> 


00054000 


00175 




IF NOT INTERACTIVE THEN QUIT(2); 


<<NO LIVE USER-QUIT>> 


00055000 


00201 


1 


GO LOOP; 


<<CONTINUE CALC>> 


00056000 


00202 


1 


EXIT: END. 




PRIMARY 


DB STORAGE=%020; SECONDARY DB STORAGE=%00113 




NO. ERR0RS-00C 


; 


NO. WARNINGS=000 




PROCESSOR TIME 


=0 


00:03; ELAPSED TIME=0:00:11 





Figure 5-7. Using the QUIT Intrinsic (2 of 2) 

In batch jobs not containing the : CONTINUE command this terminates the job. For more information 
on the :C0NTINUE command refer to the MPE V Commands Reference Manual (32033-90006). 

The form of the QUITPROG intrinsic call could be as follows: 

QUITPR0GC1); 

The parameter (1) can be any user -specified number. When the QUITPROG intrinsic executes, this 
number is printed as part of the abort message. In addition, QUITPRDG sets the system Job Control 
Word, JCW, to the value % 100000, with the QUITPROG parameter as a modifier. Thus, in this ex- 
ample, JCW would be set to %100001. 



CHANGING STACK SIZES 



When you prepare or execute a process, you specify (or allow MPE to assign by default) the size of the 
stack (Z to DB) area and the user -managed (DL to DB) area within the stack segment. Once the 
process begins execution, you can programmatically change the size of these areas, to meet new 
requirements as they arise, by altering the register offsets Z to DB or DL to DB. For example, you 
typically expand the size of these areas when you find, during process execution, that the sizes 
specified initially were not sufficient for your data requirements. Conversely, you might contract the 
size of either of these areas should your process no longer require large amounts of space for data. 
(This is a good practice as it improves overall system performance.) These changes are requested with 
the DLSIZE intrinsic for the DL to DB area and the ZSIZE intrinsic for the Z to DB area. 

If you plan to expand or contract the Z to DB or DL to DB areas programmatically, you must specify, 
at the time the stack is created, the anticipated maximum size of the stack segment. This value is 
used by MPE in allocating disc storage. The maximum stack size value is specified at preparation or 
run time with the segsize parameter of the :PREP, :PREPRUN, or : RUN command, or if you are a 
user with the Process Handling capability, after the program is running with the maxdata parameter 
of the CREATE intrinsic. 
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NOTE 



When the stack segment of a process running in 
Privileged Mode is frozen in main memory , as during an 
input/output operation, either implicitly or explicitly, 
intrinsics to change the register offsets DL to DB or Z to 
DB cannot be executed . The stack segment is frozen in 
main memory implicitly when a user's process interfaces 
directly with the input/output system. It is frozen in 
main memory explicitly by a direct call to system intrin- 
sics. When these intrinsics are called under such cir- 
cumstances, a special "frozen stack" error code is 
returned to the calling process , which then may attempt 
recovery. In general, this error implies that you should 
wait until the stack is unfrozen before reissuing the in- 
trinsic call. 

Changing the DL to DB Area Size 

You can expand or contract the area between DL and DB within the stack segment with the DLSIZE 
intrinsic. All current information within the DL to DB area is saved on expansion. On contraction, 
data within the area to be contracted is lost. (Refer to Figure 5-8.) 

A request for contraction to less than the initial DL size of the area causes the initial DL size to be 
granted and an error condition code (CCL) to be returned. If the size requested causes the stack to 
exceed the maximum size permitted to the entire stack area, Z to DL, only this maximum will be 
granted. 

Some possible applications for the DL area are : 

• Dynamically allocated I/O buffers when using the FCOPY subsystem. 

• Compiler symbol tables when programming in SPL. 

• Global storage area for library routines in Segmented Libraries. These routines typically have no 
global area storage which will retain values assigned to them between calls to the procedure. 
These routines also typically have no common storage where data can be shared by several 
procedures. If you define your conventions carefully, these library routines can use the DL area 
of the process which calls them for this kind of storage. Care must be taken, however, because 
the 10 words of the DL area located adjacent to DB are reserved for subsystem use, and some sys- 
tem routines make use of the DL area for their own storage. As long as your environment is com- 
pletely known and well defined, your main program or your library routines can get DL space and 
manage it as they choose. 

Figure 5-9 contains an SPL program that expands and contracts the DL to DB area. 



NOTE 



All addressing within the DL to DB area is DB -relative 
negative indexing. SPL is the only language which can 
access this area for you . 
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The program in Figure 5-9 reads data from $STDIN and stores it in the DL area at progressively 
lower (DB-n) addresses. Additional DL space is allocated when the next buffer would lie outside the 
current DL area. When a null record (0 length) is read, the program outputs the data on a last-in- 
first-out (LIFO) basis. After all the records are output, the DL space is collapsed to its initial alloca- 
tion and the operation begins again. The loop is terminated by entering :EDDin place of a data line. 
Note that the program was prepared ( : PREP command) with a f"1AXDATA=2000 parameter. 

Statement 00018000 of Figure 5-9 sets the DL to DB area to the original area assigned when the 
process was created (initial DL) : 

TOTALDL:=DLSIZEC0); 




Z-> 



7 

nR v 


(NEW 
AREA) 

Will 


? 
s ^ 





A CALL TO DLSIZE TO EXPAND 
THE DL TO DB AREA CAUSES 
THE DL REGISTER TO BE 
MOVED FARTHER AWAY FROM DB. 
THE NEW AREA CREATED BY 
THE EXPANSION IS ADDED 
TD THE EXISTING DL AREA. 
INFORMATION WHICH WAS 
CONTAINED IN THE OLD DL AREA 
IS NEITHER MOVED RELATIVE TO 
DB NOR ALTERED IN ANY WAY. 



DL— * 



DB » 




DATA 
LOST 



A CALL TO DLSIZE TO CONTRACT 
THE DB TO DL AREA CAUSES THE 
DL REGISTER TO BE MOVED CLOSER 
TO DB. THE DATA CONTAINED 
BETWEEN THE OLD POSITION OF 
DL AND THE NEW CONTRACTED 
POSITION OF DL IS LOST TO 
THE USER. 



Figure 5-8. Expanding and Contracting the DL to DB Area 
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PAGE 0001 HP32100A.08.01 [4W] (C) HEWLETT-PACKARD COMPANY 1980 


00001000 


00000 





$C0NTR0L USLINIT 




00002000 


00000 





BEGIN 




00003000 


00000 


1 


INTEGER IN.OUT.LGTH, 




00004000 


00000 


1 


TOTALDL:=0; 




00005000 


00000 


1 


LOGICAL PROMPT :="? " ; 




00006000 


00000 


1 


LOGICAL POINTER BUFFER: =-46; 


<<BUFFER:36 ; RESERV:10>> 


00007000 


00000 


1 






00008000 


00000 


1 


INTRINSIC FOPEN,DLSIZE,FREAD,FWRITE,QUIT; 


00009000 


00000 


1 






00010000 


00000 


1 


<<END OF DECLARATIONS) > 




00011000 


00000 


1 






00012000 


00000 


1 


IN:=F0PEN(,5J44); 


<<$STDIN>> 


00013000 


00007 


1 


IF < THEN QUIT(l); 


<<CHECK FOR ERROR>> 


00014000 


00012 


1 






00015000 


00012 


1 


0UT:=F0PEN( ,%414,1) ; 


<<$STDLIST>> 


00016000 


00022 


1 


IF < THEN QUIT(2); 


<<CHECK FOR ERROR>> 


00017000 


00025 


1 


RESTART: 




00018000 


00025 


1 


TOTALDL:=DLSIZE(0) 


<<SET DL TO INITL SIZE>> 


00019000 


00030 


1 


IF <> THEN QUIT(3) ; 


<<CHECK FOR ERROR>> 


00020000 


00033 


1 


LINEIN: 




00021000 


00033 


1 


PUSH(DL); 


<<GET CRNT DL SETTING>> 


00022000 


00034 


1 


IF TOS>@BUFFER THEN 


<<NEXT BFR OUTSIDE DL?>> 


00023000 


00036 


1 


BEGIN 




00024000 


00036 


2 


TOTALDL : =DLSIZE ( TOTALDL- 


•128);<<GET MORE DL AREA>> 


00025000 


00043 


2 


IF <> THEN QUIT(4) ; 


<<CHECK FOR ERROR>> 


00026000 


00046 


2 


END; 




00027000 


00046 


1 


BUFFER:*" " ; 




00028000 


00050 


1 


MOVE BUFFER(l) : =BUFFER , (35) 


<<BLANK READ BUFFER>> 


00029000 


00055 


1 


FWRITE (OUT, PROMPT, 1,%320) ; 


<<?PR0MPT FOR INPUT>> 


00030000 


00062 


1 


IF <> THEN QUIT(5) ; 


<<CHECK FOR ERROR>> 


00031000 


00065 


1 


LGTH:=FREAD(IN, BUFFER, 36) ; 


<<INPUT DATA>> 


00032000 


00073 


1 


IF < THEN QUIT(6); 


<<CHECK FOR ERROR>> 


00033000 


00076 


1 


IF > THEN GO EXIT; 


<<CHECK FOR :EOD>> 


00034000 


00077 


1 


IF LGTH=0 THEN 


<<NO DATA INPUT?>> 


00035000 


00102 


1 


BEGIN 




00036000 


00102 


2 


@BUFFER:=<aBUFFER+36; 


<<ADDRESS PREVIOUS BUFR>> 


00037000 


00105 


2 


GO LINEOUT; 


<<START OUTPUT PHASE>> 


00038000 


00113 


2 


END; 




00039000 


00113 


1 


@BUFFER:=@BUFFER-36; 


<<ADDRESS NEXT BUFFER>> 


00040000 


00116 


1 


GO LINEIN; 


<<CONTINUE>> 


00041000 


00117 


1 


LINEOUT: 




00042000 


00117 


1 


FWRITE(OUT, BUFFER, 36,0) ; 


<<0UTPUT DATA>> 


00043000 


00124 


1 


IF <> THEN QUIT(7); 


<<CHECK FOR ERROR>> 


00044000 


00127 


1 


IF @BUFFER>=-46 THEN GO RESTART ; <<ALL BUFRS OUT:RESTRT>> 


00045000 


00132 


1 


(PBUFFER:=<aBUFFER+36; 


<<ADDRESS PREVIOUS BUFR>> 


00046000 


00135 


1 


GO LINEOUT; 


<<CONTINUE OUTPUT PHASE>> 


00047000 


00137 


1 


EXIT: END. 





Figure 5-9. Using the DLSIZE Intrinsic (Program DLAREA) 
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Consider the following illustration of the DL to DB area : 
DL | 1 ORIGINAL DL LIMIT 



DB-46 



DB 




36 WORDS RESERVED FOR BUFFER 



10 WORDS RESERVED FOR SUBSYSTEMS OF MPE 



Statement 00006000 in Figure 5-9: 

LOGICAL POINTER BUFFER: =-46; 
sets a pointer to DB-46, which is the DB-relative address of the first word in BUFFER. 
Statement 00021000: 

PUSH(DL); 
pushes the DL register contents onto the top of the stack, and statement 00022000: 

IF T0S>®BUFFER THEN 

checks to determine whether the address of the first word of BUFFER is outside the DL to DB area. In 
other words, TOS contains the DL address from the DL register. If this value is greater than (less 
negative) the address of the first word in BUFFER, then BUFFER is outside the DL to DB area. The 
following diagram illustrates this point : 



DB-154 

DL 
(DB-128) 

DB-82 
DB-46 



DB-10 
DB 



36 WORDS 



BUFFER 
(36 WORDS) 



BUFFER 
(36 WORDS) 



BUFFER 
(36 WORDS) 



STARTING ADDRESS OF NEXT BUFFER 
IF ANOTHER RECORD READ FROM fSTDIN 
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If the DL address is DB-128, then when only one buffer is filled, the address of the next buffer is 
well within the DL to DB area. When three buffers have been filled, however, the starting address 
of the next buffer (DB-154) would be outside the DL to DB area (DB-0 to DB-128). The TOS 
(DB-128) is greater than the address of the first word in the next buffer (DB-154). 

If the next buffer would lie outside the DL to DB area, the four statements in the program beginning 
on line 00023000 add 128 words to the DL to DB area. 

Statements 00027000 and 00028000: 

BUFFER:-" "; 

MDVE BUFFERC1):=BUFFER, C35); 

fill BUFFER with blanks preparatory to reading the input from $STDIN. A prompt is displayed and 
the user enters the next record. The length of the record is assigned to LGTH in statement 00035000. 

If LGTH= 0, signaling a carriage return (no data entered), the program addresses the previous buffer 
and transfers control to LINE0UT. The contents of the buffers are written on $STDLISTon a last -in- 
first-out basis. When the original address is reached (DB-46), control is returned to RESTART and 
the procedure is repeated . 

Statement 00024000: 

TDTALDL:=DLSIZECO); 

contracts the DL to DB area back to its original size, destroying the contents of all buffers. An :E0D 
entry terminates program execution. 

Figure 5-10 shows the results when the program is run. 
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:RUN DLAREA 




? #******#****#**#***#* 




? ******************* 




7 ***************** 




7 *************** 




7 ************* 




7 *********** 




7 ********* 




7 ******* 




7 ***** 




7 *** 




7 * 




* 




*** 




***** 




******* 




********* 




*********** 




************* 




*************** 




***************** 




******************* 




********************* 




? DDDDDD 




? NNNNNN 




7 EEEEEE 




? (Enter at least one blank 


space and <CR>} 


? EEEEEE 




? HHHHHH 




? Mil II 




? 




II 1 1 1 1 


HHHHHH 




EEEEEE 




EEEEEE 




NNNNNN 




DDDDDD 




? :EOD 




END DF PROGRAM 





Figure 5-10. Changing the DL to DB Area Size (Program DLAREA) 
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Changing the Z to DB Area Size 



You can alter the size of the current Z to DB area by adjusting the register offset of the Z address 
from the DB address with the ZS I ZE intrinsic . 

The ZSIZE intrinsic moves the Z address forward (expansion) or backward (contraction) as shown 
below : 



OL 



DB 



NEW Z 




DL 



DB 



NEW Z 




EXPANSION 



CONTRACTION 



If the Z to DB area size requested exceeds the maximum size permitted for the Z to DL (stack) area, 
only the maximum size allowed is granted . 

All changes to the Z to DB area are made in increments or decrements of 1 28 words; thus the size ac- 
tually granted may differ from the size requested. For example, if the present Z to DB area size is 
128 words, a request for 129 words would result in a size of 256 words being granted. 

A ZSIZE intrinsic call could be: 

ACTSIZE:=ZSIZE(250D; 

If the maximum size for the Z to DL area permitted, an actual size granted for the Z to DB area of 
256 words would be returned to ACTSIZE. 



ENABLING AND DISABLING TRAPS 

Normally , whenever a major error occurs during the execution of a hardware instruction , a procedure 
from the System Library, or an intrinsic called by a user, the user program is aborted and an error 
message is output. You can, however, avoid immediate abort by enabling any of three software traps 
provided by MPE : 

• The arithmetic trap, for hardware instruction errors. 

• The library trap, for errors detected during execution of a system library procedure. 

• The system trap, for errors detected during execution of a system intrinsic. 
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When an error occurs , the corresponding trap , if enabled , suppresses output of the normal error mes- 
sage, transfers control to a "trap procedure" defined by you, and passes one or more parameters 
describing the error to this procedure. This procedure may attempt to analyze or recover from the 
error , or may execute some other programming path . Upon exiting from the trap procedure , control 
returns to the instruction following the one that activated the trap. In the case of the library trap, 
however, you can specify that the process be aborted when control exits from the trap procedure. 

The validity of a trap procedure, specified by the external-type label of the user trap procedure 
(plabels), depends on the code domain of the caller's code and executing mode (privileged or non- 
privileged), and on the code domain of the plabel and its mode (privileged or nonprivileged). The 
code domains are : 

PROG (User Program) SSL (System SL, non-MPE segments) 

GSL (Group SL) MPESSL (System SL, MPE segments) 

PSL (Public SL) 

If , at the time of enabling a trap procedure , the code of the caller is : 

• Nonprivileged in PROG, GSL, or PSL, plabel must be nonprivileged in PROG, GSL, or PSL. 

• Privileged in PROG, GSL, or PSL, plabel may be privileged or nonprivileged in PROG, GSL, or 
PSL. 

• Privileged or nonprivileged in non-MPE SSL, plabel cannot be in any MPESSL segment. 

Arithmetic Traps 

There are two levels of arithmetic traps: the "hardware arithmetic trap set" and the "software 
arithmetic trap". Each trap in the hardware trap set detects a particular type of hardware error, 
such as division by zero or result overflow. The software trap, if enabled, receives an internal inter- 
rupt signal from a hardware trap when an error is encountered , and transfers control to a user trap 
procedure. 

When a user process begins execution , all hardware trap set interrupt signals are enabled automatical- 
ly , but the software trap is disabled , permitting any hardware error to abort the process. Through in- 
trinsic calls, however, you can alter the ability of the hardware trap set to send signals, and that of 
the software trap to receive a signal from any particular hardware trap. Only signals received and 
accepted by the software trap can invoke a user trap procedure. 

To enable or disable the internal interrupt signals from all hardware arithmetic traps, you enter the 
AR I TRAP intrinsic call , as follows : 

ARITRAPCSTATE); 

where STATE is true (bit ( 1 5 : 1 ) = 1 ) to enable the signals from all hardware traps , or false (bit (15:1) 
= 0) to disable these signals. 

When a software arithmetic trap procedure is executed, the Index register contains the word of code 
being executed when the trap occurred. This information, plus the right stackop bit in the status 
word at Q-l of the Stack Marker, can be used to identify the offending instruction. A one-word pa- 
rameter is available, in Q-4, in which certain bits indicate the type of hardware trap invoked. The 
various traps leave the parameter in Q-4 as follows. 
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STANDARD TRAPS. 

Bit 15= Floating Point Divide By 

1 4 ■ Integer Divide By 

1 3 = Floating Point Underflow 

1 2 = Floating Point Overflow 

1 1 = Integer Overflow 

A return from the trap procedure (through an EXIT 1 instruction) will resume execution in the user 
code domain at the instruction following that which activated the trap procedure. The condition of 
the stack when the trap procedure is invoked is: 



Q-4 



USER PROGRAM 



HARDWARE TRAP TYPE 
PARAMETER 



STACK MARKER 



ARITHMETIC 

TRAP 
PROCEDURE 



EXTENDED PRECISION FLOATING POINT TRAPS. 

Bit 10= Extended Precision Overflow 
9 = Extended Precision Underflow 
8 = Extended Precision Divide By 

The address of the result operand is left on the stack in Q-5. An EXIT 2 return will resume execu- 
tion in the user code domain at the instruction following the one which caused the trap. The condi- 
tion of the stack when the trap procedure is invoked is : 



Q-5 

Q-4 

Q 



USER PROGRAM 



RESULT ADDRESS 



HARDWARE TRAP TYPE 
PARAMETER 



STACK MARKER 



ARITHMETIC 

TRAP 
PROCEDURE 
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COMMERCIAL INSTRUCTION TRAPS. 

Bit 7 = Decimal Overflow 

6 = Invalid ASCII Digit (CVAD) 

5 ■ Invalid Decimal Digit 

4 = Invalid Source Word Count (CVBD) 

3 = Invalid Decimal Operand Length 

2 = Decimal Divide By 

The parameters for the execution of the instruction are left on the stack below Q-4. To return prop- 
erly the trap handler must examine the opcode (found in the Index Register) to determine the proper 
stack decrement to use on exit . The condition of the stack when the trap procedure is invoked is : 



Q-4 



USER PROGRAM 



STACKED OPERANDS 



HARDWARE TRAP TYPE 
PARAMETER 



STACK MARKER 



ARITHMETIC 

TRAP 
PROCEDURE 



An arithmetic trap procedure is shown in Figure 5-11. The procedure FDIVZRO is a trap procedure 
to which control is passed if a divide by zero operation is attempted while a Floating Point Divide By 
software trap is enabled. Statement 00027000 of Figure 5-11 enables the Floating Point Divide By 
trap. The parameter %1 (bit (15:1) = 1) enables only the Floating Point Divide By 0. The 
©FDIVZRO passes the trap procedure as a parameter, and DUMMY 1 and DUMMY2 are dummy parameters. 

Statement 00031000 of Figure 5-11 attempts a Floating Point Divide By operation and, since the 
Floating Point Divide By trap is enabled, control is transferred to procedure FDIVZRO. The condi- 
tion of the stack at this point is : 



Q-6 

Q-5 
Q-4 



USER PROGRAM 



RESULT 



HARDWARE TRAP TYPE 
PARAMETER 



STACK MARKER 



ARITHMETIC 

TRAP 
PROCEDURE 
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The two-word floating point value of RESULT has been left at Q-5/Q-6 and the FD I VZRO procedure 
uses this for QUOTIENT. 

If QUOTIENT - (0 divided by 0), no action is taken and the procedure is exited, transferring control 
back to the user program . 

If QUOTIENT is less than 0, then the largest possible negative value is assigned to QUOTIENT. 
If QUOTIENT is not less than 0, the largest possible positive value is assigned. 



PAGE 0001 


HEWLETT-PACKARD 32100A.08.1 SPL[4W] TUE . OCT 28, 1982, 4:35 


00001000 


00000 





SC0NTR0L USLINIT 


00002000 


00000 





BEGIN 


00003000 


00000 


1 


REAL NUM:=1., 


00004000 


00000 


1 


DEN0M:=0. , 


00005000 


00000 


1 


RESULT; 


00006000 


00000 


1 


INTEGER DUMMY 1.DUMMY2; 


00007000 


00000 


1 


ARRAY DIVMSG(0:7) :="DIVIDE OPERATION"; 


00008000 


00010 


1 


ARRAY ADDMSG(0:6):="ADD OPERATION "; 


00009000 


00007 


1 




oooioooo 


00007 


1 


PROCEDURE FDIVZRO(QUOTIENT.TRAP) ; 


00011000 


00000 


1 


VALUE QUOTIENT, TRAP; 


00012000 


00000 


1 


REAL QUOTIENT; 


00013000 


00000 


1 


LOGICAL TRAP; 


00014000 


00000 


1 


BEGIN 


00015000 


00000 


2 


IF QUOTIENTS. THEN GO EXIT; <<LEAVE UNCHANGED>> 


00016000 


00004 


2 


IF QUOTIENTS. <<CHECK SIGN OF ANS>> 


00017000 


00006 


2 


THEN QUOTIENT: =%37777777777D << - LARGEST VALUE>> 


00018000 


00011 


2 


ELSE QU0TIENT:=%17777777777D; << + LARGEST VALUE>> 


00019000 


00023 


2 


EXIT: 


00020000 


00023 


2 


RETURN 1; <<DEL TRAP PARM 0NLY>> 


00021000 


00026 


2 


END; 


00022000 


00000 


1 




00023000 


00000 


1 


INTRINSIC XARITRAP, PRINT, QUIT; 


00024000 


00000 


1 




00025000 


00000 


1 


<END OF DECLARATI0NS>> 


00026000 


00000 


1 




00027000 


00000 


1 


XARITRAP(%l,<aFDIVZR0,DUMMYl,DUMMY2) ;<<ARM FP/0. TRAP>> 


00028000 


00005 


1 


IF < THEN QUIT(l); <<CHECK FOR ERR0R>> 


00029000 


00010 


1 




00030000 


00010 


1 


PRINT(DIVMSG,8,0) ; <<DIVIDE HEADING>> 


00031000 


00014 


1 


RESULT :=NUM/DEN0M; <<DIVIDE>> 


00032000 


00020 


1 




00033000 


00020 


1 


PRINT (ADDMSG, 7,0) ; <<ADD HEADING>> 


00034000 


00024 


1 


RESULT :=RESULT+RESULT; <<ADD>> 


00035000 


00030 


1 


END. 



Figure 5-11. Using the XARITRAP Intrinsic (Program ATRAP) 
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Statement 00020000 of Figure 5-11 deletes one word from the stack (the TRAP parameter at Q-4) 
and returns to the program leaving QUOTIENT (whose value is either % 3777777777 7D or 
%17777777777D) on the top of stack (once the stack marker for FDIVZRDand the trap parameter are 
deleted). 

When statement 00034000: 

RESULT: =RESULT+RESULT; 

tries to add the large value contained in RESULT to itself, the Floating Point Overflow hardware trap 
aborts the process. The Floating Point Overflow error was deliberately caused in this example 
program by assigning one of two largest possible values to RESULT and then attempting an add 
(RESULT + RESULT). In a practical program such trap recovery (causing another intentional error) 
would not be used. The result of running the example program is shown below: 

: RUN ATRAP 

DIVIDE OPERATION 
ADD OPERATION 

ABORT : ATR AP . PUB . SUPPORT . X . %26 

PROGRAM ERROR #2 FLOATING POINT OVERFLOW 

PROGRAM TERMINATED IN AN ERROR STATE. CCIERR 976) 



Library Trap 

The software library trap reacts to major errors that occur during execution of procedures from the 
System Library. When a user program begins execution, this trap is disabled automatically. You can 
enable (or disable) it with the XLIBTRAP intrinsic. When enabled, the library trap passes control to a 
trap procedure in the event of an error. This procedure, in turn, returns four words to the user 
program which contain the stack marker created when the library procedure was called by the user 
program. In addition, the trap procedure returns an integer representing the error number. When 
the procedure is completed, it either transfers control to the instruction following that which caused 
the error or aborts the process at your option. The trap procedure is defined by you, but it must con- 
form to the special format discussed in the HP 3000 Compiler Library Reference Manual 
(30000-90028). 

The XLIBTRAP intrinsic call could be as follows: 

XLIBTRAP(PLABEL,OLDPLABEL) ; 

where PLABEL is the external -type label of your trap procedure. If the value of this parameter is 0, 
the trap is disabled. OLDPLABEL is a word in which the previous plabel is returned to the user 
program. If no plabel existed previously, is returned. 
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When a library trap procedure is invoked , the condition of the stack is : 





USEE'S PROGRAM 


Q'-3 




Q'-2 




Q'-l 




Q' 






COMPILER 

UBRARY 

ROUTINES 


Q-6 


USERSTACK 


Q-5 


ERRORCODE 


Q-4 


ABORTFLAG 




USER'S TRAP PROCEDURE 



where the variables shown in Q-4 to Q-6 represent the following: 



USERSTACK 
ERRORCODE 

ABORTFLAG 



A word pointer to Q' of the stack marker placed on the stack when the 
user program called the compiler library. 

A reference parameter indicating the type of compiler library error, 
described in the HP 3000 Compiler Library Reference Manual 
(30000-90028). 

A reference parameter set before the user exits from the trap procedure. If 
true, the compiler library aborts the program with the standard error mes- 
sage (just as if no trap procedure had been executed). If false, the compiler 
library does not abort the program, and no error message is printed. In this 
case, the compiler library attempts error -recovery. 
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System Trap 

The software system trap reacts to errors occurring in intrinsics called by user programs. Typical er- 
rors are : 

• Illegal access. An attempt by a user to access an intrinsic for which he does not have access 
capability. 

• Illegal parameters. The passing to an intrinsic of parameters that are not defined for the user's 
environment. 

• Illegal environment. The DB register is not currently pointing to the user's stack area. 

• Resource violation. The resource requested by a user is either illegal or outside the constraints 
imposed by MPE. 

When a user program begins execution, the system trap is disabled automatically. When enabled by 
the XSYSTRAP intrinsic call and subsequently activated by an error, the trap transfers control to a 
trap procedure. The system trap is enabled or disabled by a XSYSTRAP intrinsic call, as follows: 

XSYSTRAP CNEWPLABEL , OLDPLABEL) ; 

where NEWPLABEL is the external -type label of your trap procedure. If the value of this parameter is 
0, the software trap is disabled. OLDPLABEL is a word to which the previous plabel is returned to 
your program. If no plabel existed previously, is returned. 

When a system trap procedure is executed because of an abort condition arising in a system intrinsic, 
the stack is readjusted to provide an eight -word parameter group between the intrinsic parameters 
and the stack marker: 



Q-11 
Q-10 
Q-9 
Q-8 
Q-7 
Q-6 
Q-5 
Q-4 
Q-3 
Q-2 
Q-1 




USER PROGRAM 


N WORDS FOR THE 
CALLABLE INTRINSIC 


PARAMETER 1 


PARAMETER 2 


PARAMETER 3 


PARAMETER 4 


PARAMETER 5 


PARAMETER 6 


PARAMETER 7 


PARAMETER 8 




STACK MARKER 






SYSTEM TRAP PROCEDURE 





N WORDS 



\ 



V EIGHT-WORD 

/ PARAMETER GROUP 



/ 
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The format of the eight- word parameter group in Q-4 through Q-l 1 is: 

9 10 15 



BITS 
Q-11 

Q-K» 

Q-9 

Q-8 

0-7 

Q-6 

0-5 

Q-4 



I 


N 


p 


p-1 


E-1 


P-2 


E-2 


P-3 


E-3 


P-4 


E-4 


P-5 


E-5 


P-6 


E-6 



PARAMETER 1 
PARAMETER 2 
PARAMETER 3 
PARAMETER 4 
PARAMETERS 
PARAMETER 6 
PARAMETER 7 
PARAMETER 8 



7 8 



where the variables represent the following : 
I Intrinsic number. 



N 



P-1 through P-6 



E-1 through E-6 



Number of callable intrinsic parameters. (To resume execution in the user 
code domain, an EXIT N+8 instruction should be executed.) 

Additional parameter information. 

Parameters modifying the error bytes (described below). If no modifying 
parameter is present, the corresponding parameter byte is set to zero. 

Error bytes. The last error code present is delimited by the value of zero in 
the following error byte. 



With these parameters, the trap procedure may take any recovery action necessary. For example, it 
may write messages, produce selective dumps, set error -indication flags, or allow interactive debug- 
ging. Finally, the procedure may either call the TERMINATE intrinsic or issue an EXIT N+8 instruc- 
tion to return to the user program (at the location following that where the trap was invoked), with 
appropriate error indications. A sample declaration for a system trap procedure, and an example of 
how you might issue an EXIT N+8 instruction , is: 



PROCEDURE 



SYSTEMTRAP 



VALUE 



LOGICAL 



CPARAMETER1 ,PARAMETER2, PARAMETER3, 
PARAMETER4 , PARAMETERS , PARAMETERG , 
PARAMETER7 , PARAMETER8) ; 

PARAMETER1 , PARAMETER2, PARAMETER3, PARAMETERS, 
PARAMETERS , PARAMETER6, PARAMETER7 , PARAMETER8 ; 

PARAMETER1 , PARAMETER2, PARAMETER3, PARAMETERS, 
PARAMETERS, PARAMETERG, PARAMETER7 , PARAMETER8; 
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BEGIN 

INTEGER N; 



<<USER MAY OUTPUT MESSAGES>> 



N:=PARAMETER1 LAND%37; «N=NUMBER OF PARAMETERS PASSED TO 

CALLABLE INTRINSIC» 

TOS:=N+X31410; «PUT "EXIT N+8" ON TOP OF STACK» 

ASSEMBLE (XEQ 0); «EXECUTE "EXIT N+8" ON TOP OF STACK» 

END; 

CONTROL-Y Traps 

If you are running a program in an interactive session, you can enable a special trap that transfers 
control from the currently executing program to a trap procedure whenever a CONTROL-Y subsys- 
tem break signal is entered from the terminal. On most terminals, the CONTROL-Y signal is trans- 
mitted by pressing the CONTROL key and the Y key simultaneously. 

When more than one process is currently running within your process tree structure, the 
CONTROL-Y signal interrupts the last process to enable the trap. 

When a process is interrupted by a CONTROL-Y signal, the following occurs: 

1 . The input/output transactions pending between the process and the terminal are halted and 
flagged as though all were completed successfully. 

2 . Control is transferred to the trap procedure for interaction . This procedure executes in the same 
mode (either privileged or nonprivileged) as the interrupted user program. The restrictions for 
operating the trap procedure are: you cannot trap from Privileged to non -Privileged Mode; the 
program Group SL/Public SL can't trap into System SL ; the System SL can trap into System SL 
only; if you are in MPE, you can trap into either MPE or a non-MPE mode; if you are not in 
MPE, you can only trap into a non-MPE mode. 

3. Control returns from the trap procedure to the interrupted program or procedure. If the inter- 
rupted program or procedure was waiting for completion of input/output (reading from or writ- 
ing to the terminal) when the CONTROL-Y signal was received, the FREADor FWRITE intrinsic 
that was executed is flagged as successfully completed when control returns from the trap proce- 
dure. If the CONTROL-Y signal was received during reading, the number of characters en- 
tered before this signal is returned to you as the value of FREAD. The "carriage" position is 
unchanged . 

If you send another CONTROL-Y signal, it is ignored unless a call to the RESETCONTROL intrinsic 
was issued at some point prior to the signal . 
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If you send a CONTROL -Y signal while MPE system code is executing on your behalf, MPE searches 
back to the last user stack marker and sets bit of RELATIVE P in that marker. No interrupt will 
occur until an EXIT instruction is executed through the above marker. The trap is recognized, a 
marker is built, and control is transferred to the trap procedure. When the trap procedure is in- 
voked , the condition of the stack is as follows : 





USER PROGRAM 
DATA 


Q-3 




Q-2 


RELATIVE P 


Q-1 




Q 




Q+1 




n 


Q+2 
Q+3 


CONTROL-Y 

TRAP PROCEDURE 

DATA 



USER STACK MARKER 



When the first instruction in the trap procedure is executed, the Q register points to the user stack 
marker and the S register points to Q+2. The trap procedure should not write data in the rightmost 
byte of the word Q+ 1 , because this word contains the number of words to be deleted from the stack 
(in addition to the stack marker) upon exit from the procedure. This value is non-zero when para- 
meters to a system procedure (which was executing when the CONTROL-Y occurred) have been left 
on the stack. On return, the trap procedure must know the value contained in Q+1 and pass it to the 
n parameter of the EXIT n instruction. The EXIT n instruction must be placed on the stack as 
follows : 

TOS:=%31400+N; 

The EXIT n instruction then is executed by an XEQ instruction. 



NOTE 



If you are a user with Privileged Mode capability, you 
should be aware of the following : 

• If your interrupted code was executing in Privileged 
Mode, your trap procedure must also be executed in 
Privileged Mode, and therefore must have Privileged 
Mode capability. 

• When your process is executing in Privileged Mode 
and a CONTROL-Y signal invokes a trap procedure, 
the trap procedure is entered with the same DB 
register setting in effect when the signal was 
received. Thus, if the DB register is pointing to an 
extra data segment rather than the user stack when 
a CONTROL-Y signal is received, it will continue to 
point to that extra data segment when the trap pro- 
cedure is entered . 
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Figure 5-12 shows a program containing a CONTROL-Y trap procedure. Statements 00022000 
through 00024000: 

LOOP: 

CNTR:=CNTR+1D; 

IF CNTRO000000D THEN GO LOOP; 

increment a double-word counter by 1 each time the loop is executed. When the counter reaches the 
value 3000000 (decimal), program execution terminates. 

The CONTROL-Y trap procedure, beginning with statement 00010000: 

PROCEDURE CONTROLY; 

assumes control whenever CONTROL-Y is entered from the terminal. The trap procedure executes, 
then control passes back to the loop . 

Statement 00012000: 

INTEGER SDEC=Q+1 ; 

equates SDEC to Q+ 1 . The, rightmost byte of Q+ 1 contains the number of words on the stack to be 
deleted (in addition to the stack marker) when the EX IT instruction executes. This value is passed to 
EX IT as the n parameter. 

The counter value is converted to an ASCII string by calling the DASCI I intrinsic, and the PRINT in- 
trinsic call displays this ASCII string on the terminal . 

The RESETC0NTR0L intrinsic call enables the CONTROL-Y trap. To take effect, this intrinsic may 
be called at any time from any procedure after the CONTROL-Y trap has been invoked. An EXIT 
instruction must be built and statement 00016000: 

TOS:=%31400+SDEC; 

accomplishes this, loading the octal value %31400 plus the value of SDEC (Q+l) onto the top of the 
stack. Statement 00017000: 

ASSEMBLE CXEQ 0); 

executes the statement on the top of the stack, which in this case is the EX IT instruction placed there 
by the previous statement . 

The CONTROL-Y trap is enabled by statement 00020000: 

X CONTRAP CSC0NTR0L Y , DUMMY ) ; 

The ©CONTROLY parameter informs the system that a procedure (CONTROLY) is being passed as a 
parameter . 
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PAGE 0001 HP32100A.08.01 [4W] (C) HEWLETT-PACKARD COMPANY 1980 


00001000 


00000 





$CONTROL USLINIT 


00002000 


00000 




BEGIN 


00003000 


00000 


1 


ARRAY HEADING(0:10):="C0NTR0L Y TRAP EXAMPLE"; 


00004000 


00013 


1 


ARRAY MSG(0:15) :="COUNTER CURRENTLY' "; 


00005000 


00020 


1 


BYTE ARRAY BMSG(*)=MSG; 


00006000 


00020 


1 


DOUBLE CNTR:=0D; 


00007000 


00020 


1 


INTEGER DUMMY, LGTH; 


00008000 


00020 


1 


INTRINSIC PRINT, XCONTRAP, QUIT, DASCII .RESETCONTROL ; 


00009000 


00020 


1 




oooioooo 


00020 


1 


PROCEDURE CONTROLY; 


00011000 


00000 


1 


BEGIN 


00012000 


00000 


2 


INTEGER SDEC=Q+1; 


00013000 


00000 


2 


LGTH : =DASCII (CNTR , 10 , BMSG(20 ) ) ; < <CONVERT COUNTER> > 


00014000 


00007 


2 


PRINT(MSG,16,0); <<OUTPUT COUNTER>> 


00015000 


00013 


2 


RESETCONTROL; <<REARM CONTROL Y TRAP>> 


00016000 


00014 


2 


TOS:-%31400+SDEC; <<BUILD EXIT INSTRUCTIONS 


00017000 


00016 


2 


ASSEMBLE (XEQ 0); <<EXECUTE EXIT>> 


00018000 


00017 


2 


END; 


00019000 


00000 


1 


PRINT(HEADING,11,0) ; <<PR0GRAM ID>> 


00020000 


00004 


1 


XC0NTRAP(@C0NTROLY, DUMMY ) ; < <ARM CONTROL Y TRAP>> 


00021000 


00007 


1 


IF < THEN QUIT(l); <<CHECK FOR ERROR>> 


00022000 


00012 


1 


LOOP: 


00023000 


00012 


1 


CNTR:=CNTR+1D; <<DOUBLE INCREMENTS 


00024000 


00023 


1 


IF CNTRO000000D THEN GO LOOP ; <<CONTINU0US L0OP>> 


00025000 


00027 


1 


END. 



Figure 5-12. Using the XCONTRAP Intrinsic (Program CONTY) 
The results of executing the program are shown below : 



: RUN CONTY 

CONTROL Y TRAP EXAMPLE 
COUNTER CURRENTLY - 125153 
COUNTER CURRENTLY = 1093923 
COUNTER CURRENTLY = 1860957 
COUNTER CURRENTLY - 2700949 









X 



> 



V 



CONTROL-Y 
"ENTERED FROM TERMINAL 



END OF PROGRAM 



TIME AND DATE INTRINSICS 



You can programmatically request the return of system timer information with the TIMER intrinsic; 
the time of day with the CLOCK intrinsic; the calendar date with the CALENDAR intrinsic; and the 
duration, in milliseconds, that a process has been running with the PRQCTIME intrinsic. 
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Obtaining System Timer Information 

A 31 -bit logical quantity representing the current system timer count can be returned to your 
program with the TIMER intrinsic. This information can be used in routines that generate random 
numbers, or in measuring the real time elapsed between two events. The resolution of the system 
timer is one millisecond; thus readings taken within a one -millisecond period may be identical. 

This quantity is reset to zero on 24-day intervals at 12 o'clock midnight. Detection and correction of 
this case between two calls to TIMER (less than 24 days apart) for computing an elapsed time interval 
can be done by adding 2,073,600,000 (the number of milliseconds in 24 days) to the result when 
subtracting a current TIMER count from a previous count with a negative result. 

Figure 5-13 contains a program that uses the system timer bit count to generate a random octal num- 
ber. This number then is converted to one of the ASCII characters ( ; ,<=>?©, or A through Z.) 

Statement 00027000: 

CBUFC5): =INTEGERCTIMER) . C1 1 :5)+%73; 

calls the TIMER intrinsic to obtain the timer count. A double-word quantity is returned as follows: 



T 



The INTEGER function strips Word 1 from this quantity, leaving a 16 -bit integer value. The low- 
order five bits change value most rapidly, and are used to obtain a decimal number from to 32. 

The octal codes for ASCII characters ;,<=>?©, and A through Z range from 000073 to 000132, or 
decimal values 58 through 90 (a difference of 32 decimal). Thus, by adding %73 to the value ob- 
tained from the low -order five bits of the system timer information , one of the above ASCII charac- 
ters is generated by the foregoing statement and assigned to the sixth position of byte array CBUF 
(CBUFCS)). The FWRITE intrinsic displays this character, and the string "TYPE" on the terminal. 
(CBUF and BUFRhave been equated in statements 00006000 and 00007000.) 

Obtaining the Current Time 

The CLOCK intrinsic returns the actual time as a double-word. The first word contains the hour and 
minute of the hour , and the second word contains seconds and tenths of seconds , as follows : 



BITS 







7 


8 




15 




HOUR OF DAY 


MINUTE OF HOUR 




SECONDS 


TENTHS OF SECONDS 



WORD 1 



WORD 2 



By using the intrinsic call TIME:=CLOCK;, the above information would be returned to the double- 
word identifier TIME. 
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00002000 
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00003000 


00001 





00004000 


00004 


1 


00005000 


00005 


1 


00006000 


00005 


1 


00007000 


00004 


1 


00008000 


00004 


1 


00009000 


00011 


1 


00010000 


00043 


1 


00011000 


00020 


1 


00012000 


00031 


1 


00013000 


00021 


1 


00014000 


00021 


1 


00015000 


00021 


1 


00016000 


00021 


1 


00017000 


00007 


1 


00018000 


00012 


1 


00019000 


00022 


1 


00020000 


00025 


1 


00021000 


00032 


1 


00022000 


00035 


1 


00023000 


00035 


1 


00024000 


00041 


1 


00025000 


00044 


1 


00026000 


00050 


1 


00027000 


00053 


1 


00028000 


00062 


1 


00029000 


00067 


1 


00030000 


00072 


1 


00031000 


00101 


1 


00032000 


00102 


1 


00033000 


00102 


2 


00034000 


00110 


2 


00035000 


00120 


2 


00036000 


00120 


1 


00037000 


00126 


1 


00038000 


00126 


2 


00039000 


00134 


2 


00040000 


00141 


2 


00041000 


00141 


1 


00042000 


00153 


1 


00043000 


00157 


1 


00044000 


00162 


1 


00045000 


00171 


1 


00046000 


00177 


1 



[4W] (C) 
USLINIT 



HEWLETT-PACKARD COMPANY 1980 



= 10; 



00A.08.01 
$C0NTR0L 
BEGIN 
BYTE ARRAY INNAME (0 :5 ):=" INPUT "; 
BYTE ARRAY 0UTNAME( : 6 ) : ="0UTPUT "; 
INTEGER IN , OUT , LGTH .DUMMY , TIME .TIMEOUT : 
ARRAY BUFR(0:3) :="TYPE X",0; 
BYTE ARRAY CBUF (*)=BUFR ; 
ARRAY INSTRUCTIONS^ :34) -"REACTION TIMER: "%6412 , 

"TYPE THE REQUESTED CHARACTER AS QUICKLY AS YOU CAN. "; 
ARRAY MSG(0:24) :="TRY AGAIN? ( Y/N) ", "WRONG CHARACTER.". 

%6412."YOU'RE TOO SLOW!"; 
ARRAY RESPONSES :16):="REACTION TIME: MILLISECONDS- 

BYTE ARRAY CRESP(*)=RESP0NSE; 

INTRINSIC FOPEN.FREAD.FWRITE.FCONTROL. ASCII, TIMER, QUIT; 
<<END OF DECLARATIONS) > 
IN:=F0PEN(INNAME,%45) ; 
IF < THEN QUIT(l); 
OUT:=FOPEN(OUTNAME,%414,%1) ; 
IF < THEN QUIT(2); 
FWR ITE (OUT , INSTRUCTIONS ,35,0) 
IF < THEN QUIT(3); 



<<$STDIN>> 
<<CHECK FOR ERROR>> 
<<$STDLIST>> 
<<CHECK FOR ERROR>> 
<<USER DIRECTIONS>> 
<<CHECK FOR ERROR>> 



LOOP: 

FCONTROL (IN, 21, DUMMY) ; 
IF < THEN QUIT(4) ; 
FCONTROL(IN, 4, TIMEOUT) ; 
IF < THEN QUIT(5) ; 



<<ENABLE TIMER READ>> 
<<CHECK FOR ERROR>> 
<<ENABLE TIMEOUT>> 
<<CHECK FOR ERROR>> 



CBUF ( 5 ) : =INTEGER (TIMER ) . ( 11 : 5 ) +%73 ; < GENERATE CHARACTER) > 

<<REQUEST USER INPUT>> 
<<CHECK FOR ERROR>> 
<<READ CHARACTERS 
<<TIMEOUT 0CCURRED>> 

<<T00 SLOW MESSAGE>> 
NEXT;<<CHECK FOR ERROR>> 

<<INCORRECT CHARACTERS 

<<WR0NG CHARACTER MSG>> 



FWRITE (0UT,BUFR,3,%320) ; 
IF < THEN QUIT(6) ; 
LGTH:=FREAD(IN,BUFR(3) ,-1); 
IF < THEN 
BEGIN 
FWRITE(0UT,MSG(16) ,9,0) ; 
IF < THEN QUIT(7) ELSE GO 
END; 
IF CBUF(5)<>CBUF(6) THEN 
BEGIN 
FWRITE(OUT,MSG(8) ,8,0) ; 
IF < THEN QUIT(8) ELSE GO NEXT;<<CHECK FOR ERRORS 

END; 
MOVE RESPONSE (7) :=" 
FCONTROL(IN,22,TIME) ; 
IF <> THEN QUITO) ; 
ASCII(TIME*10,10,CRESP(15) ) ; 
FWRITE ( OUT, RESPONSE, 17,0); 
IF < THEN QUIT(IO) ; 



<<RESET RESPONSE TIMES 
<<READ INPUT TIMES 
<<CHECK FOR ERRORS 
<<CONVERT TIMES 
<<REACTION TIMES 
<<CHECK FOR ERRORS 



Figure 5-13. Using the TIMER Intrinsic (1 of 2) 
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00047000 00202 1 NEXT: 



00048000 00202 1 
00049000 00207 1 
00050000 00212 1 
00051000 00220 1 
00052000 00224 1 
00053000 00232 1 END. 



FWRITE(OUT,MSG,8,%320) ; 

IF < THEN QUIT(ll); 

FREAD(IN,BUFR(3) ,-1) ; 

IF < THEN QUIT(12) ; 

IF CBUF(6)="Y" THEN GO LOOP; 



<<C0NTINUE TEST?>> 
<<CHECK FOR ERR0R>> 
<<GET Y/N ANSWER>> 
<<CHECK FOR ERROR>> 
<<Y-C0NTINUE TEST>> 



Figure 5-13. Using the TIMER Intrinsic (2 of 2) 



Obtaining the Calendar Date 

The CALENDAR intrinsic returns a logical value representing the year and day as follows: 
BITS 6 7 15 



YEAR OF CENTURY 



DAY OF YEAR 



In the following intrinsic call, the day and year information would be returned to the logical iden- 
tifier DATE: 

DATE:=CALENDAR; 

Obtaining Process Run Time 

The PR0CT I ME intrinsic returns a double integer value representing the duration, in milliseconds, that 
a process has been running (CPU time). 

In the intrinsic call shown below, the process run time would be returned to TIME: 

TIME:=PR0CTIME; 

Formatting Calendar Date and Time Information 

You can format the calendar date with the FMTCALENDAR intrinsic, the time of day with the 
FMTCLDCK intrinsic, and the calendar date and time of day with the FMTDATE intrinsic. These intrin- 
sics use the information returned by the CALENDAR and CLOCK intrinsics. 

The program shown in Figure 5-14 illustrates the use of these intrinsics. 
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00024 
00030 
00034 
00034 



[4W] HEWLETT-PACKARD 
USLINIT 



COMPANY 1980 



'100A.08.01 

SC0NTR0L 

BEGIN 

ARRAY F'DATE(0:8); 

BYTE ARRAY FDATE (*)=F 'DATE ; 
ARRAY F'TIME(0:4); 

BYTE ARRAY FTIME(*)=F ' TIME; 
ARRAY DATE "TIME (0:13); 

BYTE ARRAY DATETIME(*) =DATE 'TIME ; 



LOGICAL DATE; 
DOUBLE TIME; 

INTRINSIC CALENDAR, CLOCK, FMTCALENDAR, 
FMTCLOCK , FMTDATE , PRINT ; 



DATE 
TIME 



; =CALENDAR ; 
;=CL0CK; 



FMTCALENDAR (DATE , FDATE ) ; 
PRINT(F'DATE,-17,%60); 

FMTCLOCK(TIME.FTIME) ; 
PRINT(F'TIME,-8,%60) ; 

FMTDATE (DATE , TIME .DATETIME ) ; 
PRINT (DATE 'TIME, -27, %0) ; 



END. 



Figure 5-14. Using the FMTCALENDAR, FMTCLOCK, and FMTDATE Intrinsics 



JOB CONTROL WORDS 



There are three classes of Job Control Words (JCWs) in the system. User-defined JCWs are named 
and assigned values exclusively by the user. System-defined JCWs are named by the system and can 
be assigned values either by the system (under certain circumstances) or by the user. System-reserved 
JCWs are assigned values exclusively by the system. 

Any attempt by a user to assign a value to a system -reserved JCW (with either SET JCW or PUT JCW) 
will result in an error. The values of system -reserved JCWs can be returned with FIND JCW. The 
values of these JCWs can be used in assignments to other JCWs, but the user cannot assign values to a 
system-reserved JCW. System -reserved JCWs are available on MPE V releases G.01 .00 or later. 
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The name of the system -reserved JCWs are reserved words, that is, a user cannot have a JCW of the 
same name. The following is a list of the system -reserved JCWs and their meanings. 

HPDATE Indicates the day of the month. The possible range of values for HPDATEis 

1 through 31 , inclusive. 

HPDAY Indicates the day of the week. The possible range of values for HPDAY is 1 

through 7, inclusive, with 1 indicating Sunday and 7 indicating Saturday. 

HPHOUR Indicates the hour of the day on a 2 4 -hour basis. The possible range of 

values for HPHOUR is through 23, inclusive. 

HPMINUTE Indicates the minute of the hour. The possible range of values for 

HPMI NUTE is through 59 , inclusive. 

HPMONTH Indicates the month of the year. The possible range of values for HPMONTH 

is 1 through 12, inclusive, with 1 indicating January. 

HPYEAR Contains the year of the century. 



INTERPROCESS COMMUNICATION 

You can arrange for two processes belonging to the same job/session to communicate with each other 
through a Job Control Word (JCW). This word is used by systems programmers to enable a subsystem 
process to return information to the job or session that initiated that process. Such a communication 
mechanism is used by the command executors for :RUN and various subsystem commands. However, 
you may find this control word helpful in other applications. 

The SET JCW intrinsic is used to set the bits in the Job Control Word JCW. A SET JCW intrinsic call 
could be: 

SETJCWCWORD); 

where WORD is a 16-bit logical word whose bits are set by you. If you set bit (0: 1 )=1 , the system dis- 
plays the following message when your program terminates , either normally or due to an error : 

PROGRAM TERMINATED IN AN ERROR STATE CCIERR 976) 

Bits (1:15) may be set to any pattern. 
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NOTE 



In batch mode, the job is terminated unless the 
: CONT I NUE command is used . If you have a JCW of ex- 
actly % 140000, (bits (0:2) only), the "CI ERR 976" 
message is replaced by "CIERR 989, PROGRAM 
ABORTED PER USER REQUEST". Refer to the MPE V 
Commands Reference Manual (32033-90006) for a dis- 
cussion of : CONTINUE. 



The Job Control Word, JCW, can be read by a process with the GET JCW intrinsic. The form of the 
GET JCW intrinsic call is : 

JCW:=GETJCW 

The Job Control Word would be returned to JCW. 

As an example, consider a job where two processes in the same process tree pass information to each 
other through the Job Control Word . In one process , you transmit the contents of the word PR0CLNK 
to JCW. Process A sets the Job Control Word to PRDCLNK as follows: 

SETJCW(PROCLNK); 

When process B is executed, it obtains the value of JCW through the GETJCW intrinsic. In this case, 
the contents of JCW is returned to the word ST0RELNK. 

ST0RELNK:=GETJCW; 



USER -DEFINED JOB CONTROL WORDS 



MPE allows you to establish and manipulate Job Control Words including the system-defined Job 
Control Word JCW. This capability overcomes a disadvantage of using the system -defined JCW be- 
cause MPE uses JCW for status information, you cannot be sure that MPE will not modify it, thus 
destroying whatever information you may wish to pass. 

A user-defined JCW is a 16 -bit logical word which resides in an MPE-managed table. This table, 
which also holds the system -defined JCWs, is shared by all processes in a job or session; thus any 
process of a job can access any JCW in the table . 

The name of a user-defined JCW must start with a letter and be between 1 and 255 characters long. 
A user -defined JCW is established with the PUT JCW intrinsic . This intrinsic scans the JCW Table for 
a given JCW. If found, the value of the JCW is updated to the value passed by the PUT JCW intrinsic 
call. If a JCW of that name is not found, the name is added to the table and assigned the value passed 
with the name. For example, the intrinsic call: 

PUT JCWC JCWNAME, JCWVALUE, STATUS) -, 

would search the JCW Table for a name which matches the name contained in JCWNAME (a byte ar- 
ray). If the name exists, its value is updated to the value contained in JCWVALUE. If a name match- 
ing that contained in JCWNAME is not found, the name is added to the JCW Table and assigned the 
value contained in JCWVALUE. 
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The STATUS parameter of PUTJCW indicates the status of the intrinsic call and returns an integer 
value to indicate this status as follows : 

Successful execution. 

1 Error. JCWNAME is longer than 255 characters. 

2 Error. JCWNAME does not start with a letter. 

3 Error. The JCW Table is out of space . 

4 Error. Attempted to assign a value to an MPE-defined JCW value mnemonic (OK, 
WARN, FATAL, or SYSTEM). 

5 Error. Cannot assign a value to a system -reserved JCW. 

The F I NDJCW intrinsic is used to scan the JCW Table for a given JCW and return its value. Thus, the 
intrinsic call : 

F I NDJCW ( JCWNAME , JCWVALUE , STATUS ) ; 

would search the JCW Table for a JCW of the same name as that contained in JCWNAME. If a JCW of 
the same name is found, its current value is returned in JCWVALUE. If a JCW of the same name is not 
found , an error is returned in STATUS. 

The STATUS parameter of F I NDJCW indicates the status of the intrinsic call and returns an integer 
value indicating this status as follows: 

Successful execution . 

1 Error. JCWNAME is longer than 255 characters. 

2 Error. JCWNAME does not start with a letter. 

3 Error. The JCW named in JCWNAME does not exist. 



MPE MESSAGE FACILITY 

The MPE message facility consists of a message catalog (CATALOG. PUB. SYS), the HELP subsystem 
catalog (CI CAT. PUB. SYS, containing descriptions of all MPE commands), many user message 
catalogs, a program (MAKECAT.PUB.SYS) for building message catalogs, and an intrinsic 
(GENMESSAGE) used to insert parameters in messages from a catalog and print the resulting message. 

Message Catalog 

A message catalog must be a standard editor-type file containing sets of messages, that is, a numbered 
file which contains 80-byte records in a fixed format. The message sets serve to break a catalog into 
manageable portions. After a message file is created, the MAKECAT program is used to build a 
catalog that is readable by the message system. This catalog file can still be texted into the editor, but 
it now contains a directory (written as a user label by MAKECAT). 
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Messages in the catalog can be of any length and can contain up to five parameters (parameters are 
indicated in a message by the symbol " ! "). Continuation of a message is indicated by "%" or "&" at 
the end of a line. The "%" symbol indicates that the message is continued and that a carriage return/ 
line feed will be issued to the terminal. The "4" symbol indicates that the message is continued on 
the same line with no carriage return/line feed. The GENMESSAGE intrinsic ignores all blanks be- 
tween the last nonblank character of a message and the continuation character. This allows free- 
formatting of the continuation character. 

Message sets are indicated by " $SET n" starting in column 1 (the rest of the line is treated as a com- 
ment). Maximum value for n is 62. Comments can be inserted in the catalog by placing "$" in 
column 1 of a line. Message numbers are positive integers that need not be contiguous but must be in 
the file in ascending order. After processing by the program MAKECAT, the catalog file contains 
records of 80 bytes with a blocking factor of 16, in 32 extents. (The system message catalog is only 
one extent, however.) The format of the message catalog is as follows: 

$SET 1 SYSTEM MESSAGES 

1 LDEV#!IN USE BY FILE SYSTEM 

2 LDEV#!IN USE BY DIAGNOSTICS 

3 LDEWIIN USE, DOWN PENDING 
5 IS "!" ON LDEV#! CY/N)? 



• 
$MESSAGE 35 IS TWO LINES LONG, A PARAMETER STARTS THE (Comment) 
$FIRST LINE, AND THE SECOND LINE IS ,, HP32002" (Comment) 

35! X 
HP32002B.00.! 



• 
276 LDEV # FOR "!" ON ! CNUM)! 
$ 

$SET 2 CI ERROR MESSAGES 

82 STREAM FACILITY NOT ENABLED: SEE OPERATOR. CC I ERR 82) 
200 MORE THAN 30 PARAMETERS TO BUILD COMMAND. CC I ERR 200) 



204 FILE COMMAND REQUIRES AT LEAST TWO PARAMETERS, INCLUDING THE % 
FORMAL NAME OF THE FILE.CCIERR 204) 

MAKECAT Program 

The program MAKECAT. PUB. SYS is used to build message catalogs (and HELP catalogs). The 
program's input file has the formal designator I NPUT. The program has the following entry points : 

Default entry point Reads from the input file and builds a temporary file with the formal 

designator CATALOG. Also renames any old temporary CATALOG to CATnn, 
using an incremental numbering scheme (for example , CAT1 , CAT2) . 

BUILD To use BUILD as the entry point, you must logon as MANAGER. SYS. Reads 

from the input file, builds the system message catalog (formal designator 
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CATALOG), and installs the message system. Existing catalog is renamed 
CATnn using the incremental numbering scheme as for the default entry 
point. Installation of the message system means moving the directory con- 
tained in the user label of the catalog into a data segment. The Data 
Segment Table (DST) number and the disc address of CATALOG are placed 
in the system global area. The message system may be installed while the 
system is running. 

DIR To use DIR as the entry point you must logon as MANAGER. SYS. Installs the 

system message catalog (does not build a new one). Opens input file, moves 
the directory in the CATALOG into a data segment, and places the DST 
number and disc address of CATALOG in the system global area. This entry 
point may be used when the message system seems to be malfunctioning, 
but the catalog is intact. (For example, MPE is issuing "MISSING MSG 
SET=mm. MSG=nn" at terminals and the System Console.) This may be 
done while the system is running . 

HELP Used to build the HELP catalog. Reads input file and builds a HELP 

catalog (formal designator HELPCAT) . 

To use MAKECAT to build your own message catalog , enter : 

: FILE INPUT=CAT1S 

: RUN MAKECAT .PUB. SYS ** No entry point ** 

••VALID MESSAGE CATALOG ** Printed if no errors in catalog CAT15 ** 

: SAVE CATALOG 

To use MAKECAT to modify the system message catalog : 

1 . Text CATALOG . PUB . SYS into the Editor . 

2. Make the desired changes. 

3. Keep the file under a new name and exit the Editor. 

4 . Logon as MANAGER . SYS, and enter : 

: FILE INPUT =catname. group. account 
: RUN MAKECAT, BUI LP 
**NEW CATALOG INSTALLED 

To reinstall the message catalog if MPE is printing "MISSING MSG. SET=rm?. MSG=nn, " enter: 

: HELLO MANAGER. SYS 



FILE INPUT=CATALOG 



RUN MAKECAT, DIR 
**NEW CATALOG INSTALLED 

To build a HELP catalog for the Command Interpreter , enter : 

: HELLO MANAGER. SYS 



PURGE CI CAT 



FILE INPUT '^catalog, group. account 



RUN MAKECAT, HELP 



END OF PROGRAM 
: RENAME HELPCAT, CI CAT 
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Using GENMESSAGE to Insert Parameters in Messages 

The GENMESSAGE intrinsic can be used to access the MPE message facility. GENMESSAGE is called with 
a set number , a message number , and any values to be substituted in the message . 

The message facility fetches the message from a message catalog , inserts parameters , and then routes 
the message to a file. It then returns the message in a buffer to the calling program, and/or prints 
the message on SSTDLIST. 

GENMESSAGE expects the catalog file to be a standard 80-byte Editor file with valid data, including 
continuation characters "&" and "%", to be in positions 1 through 72. Data found in positions 73 and 
above will not be included when the message is formed to go to the file or message buffer . 

In order to use the message catalog, the program must first open the message catalog, then call 
GENMESSAGE with the file number, message set number, and message number. 



NOTE 



The file must be opened with f options OLD, 
PERManent, ASCII (f options 5), and aoptions NOBUF 
and MULTI -record access (aoptions %420). 

Parameters may be inserted into the message from the catalog. The parameters are passed to the mes- 
sage with the par ami , param2, param3, param4, and param5 parameters in the GENMESSAGE intrin- 
sic call and are inserted in the message wherever a " !" is found. Parameters are inserted in the fol- 
lowing order: paraml substitutes for the leftmost " ! " in the message, param2 for the next leftmost, 
and so forth. If paramfn) is present, param(n-l) must be present (that is, you cannot specify param3 
unless paraml and param2 are specified.) 

Figure 5-15 contains a simple program that inserts the value 95 into message number 201 in message 
set 1 in the message catalog CATALDG . PUB . SYS. The complete message is then displayed on the ter- 
minal. Note that the file CATALOG . PUB . SYS is equated to CATALOG with a :FILE command; then 
the name CATALOG is used in the FOPENcall (passed to FOPENin byte array BUFF). Note also that the 
file is opened with aoptions NOBUF and MULTI-record access (aoptions %420). The message set (1) 
and message number (201) are included as parameters in the GENMESSAGE call. The parameter par- 
mask is set to % 10000 and paraml (NUMBER) has the value 95. The complete message is returned in 
BUFF, which is then printed on the terminal with the PR I NT intrinsic. 



APPLICATION MESSAGE FACILITY 



Native Language Support provides the capability for programmers to produce localized applications. 
Translated program messages may be printed in the language of a user , and data manipulation may be 
done according to the rules of a particular language . 

Information on GENCAT, the application message facility, appears in the Native Language Support 
Reference Manual (32414-90001). 
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:SPLPREP TEST, MSGTEST 



PAGE 0001 
00001000 00 
00002000 00 
00003000 00 
00004000 00 
00005000 00 
00006000 00 
00007000 00 
00008000 00 
00009000 00 
00010000 00 
00011000 00 
00012000 00 
00013000 00 
00014000 00 
00015000 00 
00016000 00 
00017000 00 
00018000 00 
00019000 00 
PRIMARY DB 
NO. ERRORS 
PROCESSOR 



HP32100A.08.01 [4W] (C) HEWLETT-PACKARD COMPANY 1980 
000 $C0NTR0L USLINIT 
BEGIN 



000 
000 
000 
000 
000 
000 
000 
000 
000 
000 
016 
026 
031 
031 
045 
045 
051 
051 



BYTE ARRAY BUFF(0:255); 
ARRAY OUTBUFF(*)-BUFF; 

INTEGER FILENUM,MSGLEN,NUMBER=95; 

INTRINSIC FOPEN.PRINTFILEINFO.GENMESSAGE, PRINT; 

MOVE BUFF := "CATALOG "; 
FILENUM:=FOPEN(BUFF,5,%420); 
IF <> THEN PRINTFILEINFO(FILENUM) ; 

MSGLEN : =GENMESSAGE ( FILENUM ,1,201, BUFF , , %10000 , NUMBER ) 

PRINT(OUTBUFF,-MSGLEN,0J; 



END. 
_STORAGE=%0O5; 
=0000; 
TIME=0:00:0O; 



SECONDARY DB STORAGE=%00200 
NO. WARNINGS=000O 
ELAPSED TIME*0:00:29 



END OF COMPILE 



END OF PREPARE 
SAVE MSGTEST 

FILE CATALOG=CATALOG.PUB.SYS 
RUN MSGTEST 

LOG FILE NUMBER 95 IS ON 

END OF PROGRAM 



Figure 5-15. GENMESSAGE Intrinsic Example 
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Programs running under MPE at any batch input device or terminal may return the following types of 
error messages: 

• Command Interpreter Error Messages which report fatal errors that occur during the interpreta- 
tion or execution of an MPE command . 

• Command Interpreter Warning Messages which report unusual conditions that occur during com- 
mand interpretation or execution but that may not necessarily be detrimental to the processing of 
the job or session . 

• Run -Time Messages which denote conditions that abort the running program, unless an ap- 
propriate error trap has been enabled . 

• User Messages which are sent to you by other users currently running jobs or sessions. 

• Operator Messages which are sent to you by the System Operator . 

• System Messages which denote miscellaneous conditions that terminate or otherwise affect the 
job/session, such as an abort requested by the System Operator. 

Other messages may be received only at the System Console, such as System Operator messages and 
System Failure messages: 

• System Operator Messages 

- Status Messages indicate the current status of jobs/sessions or input /output devices. 

- Input/Output Messages request service for, and report errors on, input/output devices. 

- User Messages , sent by users to the System Operator . 

• System Failure Messages 

- System Failure Messages. 

- Cold Load Error Messages. 



RUN-TIME MESSAGES 



Your program can be aborted as a result of any of the following general types of run -time errors: 

• Special violations: those detected by the MPE internal interrupt structure (arithmetic traps, 
bounds violations, stack overflow, etc) are "program errors" and are described in Table A-l . 
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• Explicit calls to the QUIT intrinsic. 

• Explicit calls to the QU I TPRDG intrinsic . 

• Violations of other callable intrinsics (listed in Table A- 2), such as passing of illegal parameters or 
the invoking of an intrinsic without having the required capability class . 

If an appropriate error trap has been armed, control transfers to the trap procedure which may at- 
tempt recovery or take some other action. But if no trap has been armed for the type of error en- 
countered, MPE transmits a run-time (abort) message to the user's output device and terminates the 
user's process. In a multi -process structure, QUIT aborts only the violating process, but all other er- 
rors abort the entire program. 

If the aborted program was running in a batch job, the job is aborted or terminated (if no : CONTINUE 
command overrides termination). 

If the aborted program was running in a session, control of the session is returned to you at the 
terminal . 



NOTE 



An abort -error will occur if a user process invokes cer- 
tain callable intrinsics when the DB register is not point- 
ing to its normal position (for example, DB is pointing at 
an extra data segment). If this happens and a user trap 
procedure is invoked, the DB register is reset to the 
normal position before the trap procedure is entered . 

The format for run -time error messages is: 

ABORT zpname . segment . location : sname . segment . location 

h H h H 

p-field s-field 

msgtype#msgno:<message>[ .paxKzm ,Z, number] 

h H 

m-field (from 1 to 7 lines) 

Where : 

p-field Is the location of the last instruction executed. 

s-field Is output only if the abort occurred when executing code belonging to a 

library segment referenced by the user program. The field provides the in- 
struction location within the library segment that initiated the abort . 
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Within the p- field and s -field, the parameters are: 
pname 



sname 



segment 
location 



The name of the program file containing the user's program, group, and 
account name. 

In the special case of a process having been procreated from a segment in a 
segmented library (SL) (for example, the Command Interpreter), an as- 
terisk (*) is output followed by the SL name in symbolic form. 

The symbolic name of the SL in which the segment exists: 

SYSL - System SL 
PUSL - Public SL 
GRSL - Group SL 

The logical number of the code segment relating to either the program or 
SL, whichever is appropriate. 

The location in the code segment. This is expressed in terms of the dis- 
placement (P-PB), where PB is the absolute address of the base of the code 
segment . 



NOTE 



Octal numbers are indicated by a percent sign (%) 
preceding the number. 

If the stack is completely destroyed and no valid stack 
markers can be found that define a user environment, 
then the subfields previously described will be output 
containing a question mark (?). 



The m- field contains the error message text. The parameters within the m- field are: 

msgtype is one of : 

PROGRAM TYPE 
ERROR: INTRINSIC 
RUN-TIME ERROR 
CREATE ERROR 
ACTIVATE ERROR 
SUSPEND ERROR 
MYCOMMAND ERROR 
LOCKGLORIN ERROR 
LOADER ERROR 
FILESYSTEM ERROR 

and corresponds to the names listed in Tables A-l through A- 9. For a listing of File System Errors 
refer to the discussion on the FCHECK intrinsic in Section II. Guide (30000-90049). 



A-3 



MPE Diagnostic Messages 

msgno A message number in the appropriate message table. 

message The text of the message. 

number The number of the invalid parameter passed to an intrinsic (the message 

will read: PARAM=). 

Some examples of run -time messages are: 

BINARY was called with an invalid byte address: 

ABORT :BIN.ED.MPE.%0.%12 

ERROR : I NTR I NS I C#62 : B I N AR Y 

RUN-TIME ERR0R#5 PARAMETER ADDRESS VIOLATION.PARAM #1 

The program was in an infinite loop doing a DUP instruction : 

ABORT :OV.ED.MPE%0.%177777 
PROGRAM ERROR#20 : STACK OVERFLOW 

A return was made from a nonprivileged segment to a privileged segment : 

ABORT :PRIV.ED.MPE%0.%3 

PROGRAM ERROR #6 : PRIVILEGED INSTRUCTION 

The program called the QUIT intrinsic with a parameter of 1 5: 

ABORT :QUIT.ED.MPE.X0.%1 

PROGRAM ERROR #18 : PROCESS QUIT.PARAM=15 

Nearly all CST entries were allocated and the program tried to create a process which required more 
CSTs than were available : 

ABORT :EDIT0R.PUB.SYS.%2.X7 

ERROR INTRINSIC #100: CREATE 

CREATE ERROR #30 :L0AD ERROR 

LOADER ERR0R#65 : UNABLE TO OBTAIN CST ENTRIES 

The program tried to activate a nonexistent process : 

ABORT :EDIT0R.PUB.SYS.%2.%13 

ERROR INTRINSIC #104: ACTIVATE 

ACTIVATE ERROR #21 :ACTIVATION OF MAIN PROCESS NOT ALLOWED 
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Table A- 1 . "PROGRAM TYPE " Error Messages 



MESSAGE 
NO. 



MESSAGE 



1 

2 
3 
4 
5 
6 
7 

a 

9 
10 

ii 

12 
13 
14 
15 
16 
17 
18 
19 

20 



21 

22 
23 
24 

25 
26 
27 
28 

29 
30 
31 



UNDERFLOW 
DMDE BY ZERO 



INTEGER OVERFLOW 
FLOATING POINT OVERFLOW 
FLOATING POINT UNDERFLOW 
INTEGER DIVIDE BY ZERO 
FLOATING POINT DMDE BY ZERO 
PRIVILEGED INSTRUCTION 

ILLEGAL INSTRUCTION 

EXTENDED PRECISION OVERFLOW 

EXTENDED PRECISION 

EXTENDED PRECISION 

DECIMAL OVERFLOW 

INVALID ASCII DIGIT 

INVALID DECIMAL DIGIT 

INVALID WORD COUNT 

INVALID DECIMAL OPERAND LENGTH 

DECIMAL DIVIDE BY ZERO 

STT UNCALLABLE 

PROCESS QUIT-<number> 

PROGRAM QUIT=<numb«r> 

STACK OVERFLOW 



PROGRAM KILLED 

INVALID STACK MARKER 
ADDRESS VIOLATION 
BOUNDS VIOLATION 

NONRESPONDING MODULE 
DATA PARITY 
MEMORY PARITY 
SYSTEM PARITY 

STACK UNDERFLOW 
CST VIOLATION 
STT VIOLATION 



\ 



/ 



\ 



> 



S LOGIC ERROR IN THE PROGRAM 



/ 

<number> Is the value passed to the QUITPROG or 
QUIT intrinsic by the terminating process. (This 
value is output only if it is not zero.) 

Logic error in the program. Probably looping 
and adding to the stack. May require larger 
MAXDATA when preparing program. 

Program aborted from an external source. 
Possible logic error in program. 



- Possible hardware problem. 



Logic error in program. Probably invalid CST or STT 
discovered by hardware. Explicit PCAL from TOS 
may have referenced nonexistent CST or STT. 
May be bad program file. 



Table A-2. "ERROR INTRINSIC " Message Numbers 



MESSAGE 
NO. 


INTRINSIC 


MESSAGE 
NO. 


INTRINSIC 


1 
2 
3 
4 
5 


FDPEN 

FREAD 

FWRITE 

FUPDATE 

FSPACE 


6 

7 
8 

10 
11 


FPQINT 

FREADDIR 

FCLOSE 

FCHECK 

FGETINFD 
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Table A- 2. "ERROR INTRINSIC" Message Numbers (Continued) 



MESSAGE 




MESSAGE 




NO. 


INTRINSIC 


NO. 


INTRINSIC 


12 


FREADSEEK 


74 


DBINARY 


13 


FCDNTROL 


75 


DASCII 


14 


FSETMQDE 


76 


QUIT 


15 


FLOCK 


77 


STACKDUMP 


16 


FUNL0CK 


78 


SETDUMP 


17 


FRENAME 


79 


RESETDUMP 


18 


FRELATE 


80 


LOADPROC 


19 


FREADLABEL 


81 


UNLOADPROC 


20 


FWRITELABEL 


82 


INITUSLF 


21 


PRINTFILEINFD 


83 


ADJUSTUSLF 


22 


IOWA IT 


84 


EXPANDUSLF 


23 


FINTEXIT 


85 


PUTJCW 


24 


FLABELINFO 


86 


FINDJCW 


25 


F INSTATE 


87 


GET INFO 


30 


GETLOCRIN 


99 


DEBUG 


31 


FREELOCRIN 


100 


CREATE 


32 


LOCKLDCRIN 


101 


CREATEPROCESS 


33 


UNLOCKLOCRIN 


102 


KILL 


34 


LOCKGLORIN 


103 


SUSPEND 


35 


UNLQCKGLORIN 


104 


ACTIVATE 


36 


LOCRINOWNER 


105 


GETORIGIN 


40 


TIMER 


106 


MAIL 


42 


PROCTIME 


107 


SENDMAIL 


43 


CALENDAR 


108 


RECEIVEMAIL 


44 


CLOCK 


109 


FATHER 


45 


PAUSE 


110 


GETPROCINFO 


50 


XARITRAP 


111 


PROCINFO 


51 


ARITRAP 


112 


GETPROCID 


52 


XLIBTRAP 


120 


GETPRIORITY 


53 


XSYSTRAP 


130 


GETDSEG 


54 


XCONTRAP 


131 


FREEDSEG 


55 


RESETCONTROL 


132 


DMOVEOUT 


56 


CAUSEBREAK 


133 


DMOVIN 


60 


TERMINATE 


134 


ALTDSEG 


61 


CTRANSLATE 


135 


DLSIZE 


62 


BINARY 


136 


ZSIZE 


63 


ASCII 


139 


SWITCHDB 


64 


READ 


180 


JOBINFD 


65 


PRINT 


191 


PTAPE 


66 


PRINTOP 


200 


GETPRIVMODE 


67 


PRINTOPREPLY 


201 


GETUSERMODE 


68 


COMMAND 


210 


OPENLOG 


69 


WHO 


211 


WRITELOG 


70 


SEARCH 


212 


CLOSELOG 


71 


MYCOMMAND 


214 


LOGSTATUS 


72 


SETJCW 


215 


LOGINFO 


73 


GETJCW 


305 


FERRMSG 
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Table A- 3. "RUN-TIME" Error Messages. 



MESSAGE 
NO. 



MESSAGE 



ILLEGAL DB REGISTER 
ILLEGAL CAPABILITY 
OMITTED PARAMETER 
INCORRECT REGISTER 
PARAMETER ADDRESS VIOLATION 
PARAMETER END ADDRESS VIOLATION 
ILLEGAL PARAMETER 
PARAMETER VALUE INVALID 
INCORRECT Q REGISTER 



Run-time errors are discovered by MPE performing parameter checking before attempting 
certain operations. They are caused by a logic error in the program. 



Table A- 4 . "CREATE " Error Messages 



UNKNOWN SUBQUEUE NAME (CREATE ERROR 20) 

SUBQUEUE 'A' REQUESTED WITHOUT FROZEN STACK CCREATE ERROR 21) 

INSUFFICIENT CAPABILITY FOR NONSTANDARD SUBQUEUE CCREATE ERROR 23) 

UNKNOWN PORTION OF MASTER QUEUE CCREATE ERROR 24) 

INSUFFICIENT CAPABILITY FOR MASTER QUEUE CCREATE ERROR 2S) 

ABSOLUTE PRIORITY REQUESTED WITHOUT CAPABILITY CCREATE ERROR 26) 

ILLEGAL PRIORITY CLASS SPECIFIED CCREATE ERROR 27) 

PRIORITY OMITTED WHILE FATHER PROCESS IN MASTER QUEUE CCREATE ERROR 28) 

PRIORITY RANK RESERVED TO SUPERVISOR CAPABILITY CCREATE ERROR 29) 

LOAD ERROR CCREATE ERROR 30) 

LACK OF SYSTEM RESOURCE CCREATE ERROR 31 ) 

MAXIMUM ACCOUNT PRIORITY EXCEEDED CCREATE ERROR 32) 



Table A- 5. "ACTIVATE" Error Messages. 



ACTIVATION OF SYSTEM PROCESS NOT ALLOWED CACTIVATE ERROR 20) 
ACTIVATION OF MAIN PROCESS NOT ALLOWED CACTIVATE ERROR 21) 



Table A - 6 . "SUSPEND " Error Messages 



INSUFFICIENT CAPABILITY C SUSPEND ERROR 20) 
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Table A- 7. "MYCOMMAND" Error Message 



PARSED PARAM DF CDMIMAGE > 255 CHARACTERS 



Table A- 8 . "LOCKGLORIN " Error Messages 



INCORRECT PASSWORD FOR RIN 

ONLY ONE RIN CAN BE LOCKED 

RIN IS NOT ALLOCATED 

RIN IS TOO LARGE FOR THE RIN TABLE 

RIN IS NOT GLOBAL RIN 



Table A-9. "LOADER" Error and Warning Messages 



ILLEGAL SEARCH CLOAD ERR 20) 

UNKNOWN ENTRY POINT (LOAD ERR 21) 

TRACE SUBSYSTEM NOT PRESENT (LOAD ERR 22) 

STACK SIZE TOO SMALL CLOAD ERR 23) 

MAXDATA TOO LARGE CLOAD ERR 24) 

DATA SEGMENT TOO LARGE (LOAD ERR 25) 

PROGRAM LOADED IN OPPOSITE MODE CLOAD ERR 26) 

SL BINDING ERROR (LOAD ERR 27) 

INVALID SYSTEM SL FILE CLOAD ERR 28) 

INVALID PUBLIC SL FILE CLOAD ERR 29) 

INVALID GROUP SL FILE CLOAD ERR 30) 

INVALID PROGRAM FILE CLOAD ERR 31) 

INVALID LIST FILE CLOAD ERR 32) 

CODE SEGMENT TOO LARGE CLOAD ERR 33) 

PROGRAM FILE'S EXTENT MAXIMUM MUST BE ONE CLOAD ERR 34) 

DATA SEGMENT TOO LARGE CLOAD ERR 35) 

DATA SEGMENT TOO LARGE CLOAD ERR 36) 

TOO MANY CODE SEGMENTS CLOAD ERR 37) 

TOO MANY CODE SEGMENTS CLOAD ERR 38) 

ILLEGAL CAPABILITY CLOAD ERR 39) 

TOO MANY PROCEDURES LOADED CLOAD ERR 40) 

UNKNOWN PROCEDURE NAME CLOAD ERR 41 ) 

INVALID PROCEDURE NUMBER CLOAD ERR 42) 

ILLEGAL PROCEDURE UNLOAD CLOAD ERR 43) 

ILLEGAL SL CAPABILITY CLOAD ERR 44) 

INVALID ENTRY POINT CLOAD ERR 45) 

TEMPORARY PROGRAM FILE ILLEGAL (LOAD ERR 46) 

UNABLE TO OPEN SYSTEM SL FILE CLOAD ERR 50) 

UNABLE TO OPEN PUBLIC SL FILE CLOAD ERR 51) 
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Table A- 9. "LOADER" Error and Warning Messages (Continued) 



UNABLE TO OPEN GROUP SL FILE CLOAD ERR 52) 

UNABLE TD OPEN PROGRAM FILE CLOAD ERR 53) 

UNABLE TO OPEN LIST FILE CLOAD ERR 54) 

UNABLE TO CLOSE SYSTEM SL FILE CLDAD ERR 55) 

UNABLE TO CLOSE PUBLIC SL FILE CLOAD ERR 56) 

UNABLE TO CLOSE GROUP SL FILE CLOAD ERR 57) 

UNABLE TO CLOSE PROGRAM FILE CLOAD ERR 58) 

UNABLE TO CLOSE LIST FILE CLOAD ERR 59) 

EOF OR I/D ERROR ON SYSTEM SL FILE CLOAD ERR 60) 

EOF OR I/O ERROR ON PUBLIC SL FILE CLOAD ERR 61) 

EOF OR I/O ERROR ON GROUP SL FILE CLOAD ERR 62) 

EOF OR I/O ERROR ON PROGRAM FILE CLOAD ERR 63) 

EOF OR I/O ERROR ON LIST FILE CLOAD ERR 64) 

UNABLE TO OBTAIN CST ENTRIES CLOAD ERR 65) 

UNABLE TO OBTAIN PROCESS DST ENTRY CLOAD ERR 66) 

UNABLE TO OBTAIN MAIL DATA SEGMENT CLOAD ERR 67) 

UNABLE TO CREATE LOAD PROCESS CLOAD ERR 68) 

UNABLE TO OBTAIN CSTX ENTRIES CLOAD ERR 69) 

SEGMENT TABLE OVERFLOW CLOAD ERR 70) 

UNABLE TO OBTAIN SUFFICIENT DL STORAGE CLOAD ERR 71) 

ATTIO ERROR CLOAD ERR 72) 

UNABLE TO OBTAIN VIRTUAL MEMORY CLOAD ERR 73) 

DIRECTORY I/O ERROR CLOAD ERR 74) 

PRINT I/O ERROR CLOAD ERR 75) 

ILLEGAL DLSIZE CLOAD ERR 76) 

ILLEGAL MAXDATA CLOAD ERR 77) 

PROGRAM ALREADY ALLOCATED CLOAD ERR 80) 

ILLEGAL PROGRAM ALLOCATION CLOAD ERR 81) 

ILLEGAL PROGRAM DEALLOCATION CLOAD ERR 83) 

PROCEDURE ALREADY ALLOCATED CLOAD ERR 84) 

ILLEGAL PROCEDURE ALLOCATION CLOAD ERR 85) 

PROCEDURE NOT ALLOCATED CLOAD ERR 86) 

ILLEGAL PROCEDURE DEALLOCATION CLOAD ERR 87) 

LMAP NOT AVAILABLE CLOAD WARN 88) 

PROGRAM LOADED WITH LIB = S CLOAD WARN 89) 

PROGRAM LOADED WITH LIB = P CLOAD WARN 90) 

PROGRAM LOADED WITH LIB = G CLOAD WARN 91) 

ATTEMPTING TO ALLOCATE OR DEALLOCATE PROGRAM FROM NON-SYSTEM & DISC 

CLOAD ERR 92) 
UNABLE TO MOUNT PROGRAM FILE'S HOME VOLUME SET CLOAD ERR 93) 
UNABLE TO MOUNT SYSTEM SL'S HOME VOLUME SET CLOAD ERR 94) 
UNABLE TO MOUNT PRIVATE SL'S HOME VOLUME SET CLOAD ERR 95) 
UNABLE TO MOUNT GROUP SL'S HOME VOLUME SET CLOAD ERR 96) 
UNABLE TO LOAD REMOTE PROGRAM FILE CLOAD ERR 97) 
UNABLE TO CONVERT OLD FORMAT CLOAD ERR 98) 
UNABLE TO OBTAIN DST FOR LOGICAL MAP CLOAD ERR 99) 
TOO MANY MAPPED SEGMENTS CLOAD ERR 100) 
SEGMAP TOO BIG CLOAD ERR 101) 
UNABLE TO EXPAND SEGMAP CLOAD ERR 102) 
UNABLE MANY DYNAMIC LOADS ON PROCEDURE CLOAD ERR 103) 
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USER MESSAGES 



When your batch job or session receives a message from another user's job or session , that message ap- 
pears in the following format : 

FROM/ i _ >num,username . acctname /message 

The parameters have the following meanings: 

mm The job/session number. 

username acctname The names of the transmitting job/session and user, and the name of the 

account under which it is running. 

message The message. 

As an example, if a user identified as BOB running a session under an account named MPE, sends a 
message to you that he is changing the name of a file frequently used by both programs you would see 
the following message : 

FROM/S106 BOB.MPE/DO NOT USE FILE TR7 



OPERATOR MESSAGES 

When your batch job or session receives a message from the Operator, that message appears in one of 
two formats, depending on its degree of urgency. Urgent messages (Operator Warnings) which pre- 
empt any form of input/output being conducted on the standard list device, appear in the same for- 
mat as user messages : 

OPERATOR WARNING/messag'e 

where message is the message text. 

Less serious messages, used for normal communication between the Operator and you, do not pre- 
empt input/output in progress , and appear on the standard list device in this format : 

FR0M/S3, OPERATOR . SYS/message 

Once again message is the message text . 



SYSTEM MESSAGES 



Miscellaneous conditions that terminate or otherwise affect your job/session are reported through sys- 
tem messages. These messages may appear, asynchronously, during the course of running a job/ses- 
sion on the standard list device. Table A- 10 lists the system messages and their meanings. 
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Table A - 1 . System Messages 



CAN'T INITIATE NEW SESSIONS NOW 

A new session cannot be initiated due to one of the following problems : 

1 . Insufficient system resources to start job. 

2. Session limit would be exceeded (see =LIMITand =L0G0FF). 

3. Requestor's input priority ( INPRI=) is not greater than current jobfence. 



NOTE 



System Operators can bypass rejections due to 2 and 3 by 
supplying ; H I PR I on the : HELLD and : JOB commands . 



* i JOB SION> ABORTED BY SYSTEM MANAGEMENT* 

The job/session has been aborted by the System Operator through the appropriate 
command. An immediate logoff takes place. 



*^0B SI0N> HAS EXCEEDED TIME LIMIT* 

The job/session has exceeded the time limit which was specified in the TIME= parame- 
ter of the JOB/ HELLO command. An immediate logoff takes place. 



WARNING: PRIORITY-*** 

The priority passed to the CREATE intrinsic resulted in a conflict with another process, 
and the priority then assigned was XXX instead of the requested value. 



LMAP NOT AVAILABLE 

LMAP of the process being created , or program file being run , is not available because 
the code segments are already loaded. 



•♦POWER FAIL 

Power failure has occurred and automatic restart is in progress. It is possible that a 
character has been lost due to a transmission error when the power failure occurred . 
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FILE INFORMATION DISPLAY 



In addition to Command Interpreter and run -time (abort) error messages, certain file input/output 
errors result in the output of a file information display if the caller of the file system intrinsic sub- 
sequently calls PRINTFILEINFO. For files not yet opened, or for which the FQPEN intrinsic failed, 
this display appears as in the example below . 



+-F- 1 -L-E— I -N-F-O-R-M-A-T- 1 -0-N 
FILE NUMBER 5 IS UNDEFINED. 
ERROR NUMBER: 2 RESIDUE: 
BLOCK NUMBER: NUMREC 



D-I-S-P-L-A-Y+ 



CHORDS) 



(Line 1 ) 
(Line 2) 
(Line 3) 



In this display, the lines indicated show the following information: 
Line Content 

1 A warning that there is no corresponding file open. 

2 "ERROR NUMBER" indicates the last FOPEN error for the calling program. 

"RESIDUE" is the number of words not transferred in an input/output 
request; since no such request applies in this case, this is zero. 

3 The "BLOCK NUMBER" and "NUMREC" fields will always be zero in this 

short form. 

For files that were open when a CCG (end-of-file error) or CCL (irrecoverable file error) was 
returned , the file information display appears as shown in this example : 



+-F- 1 -L-E— I -N-F-O-R-M-A-T- 1 -0-N— D- 1 -S-P-L-A-Y+ 

FILENAME IS I N . VOLLMER . CL I FTON ! (Line 1 

FOPTIDNS: NEW, ASCII , FORMAL , F , NOCCTL , FEQ , ! (Line 2 

NOLABEL ! (Line 3) 

INPUT,NOMR,NOLOCK,DEF,BUF,NOMULTI, ! (Line 4) 

WAIT,NOCOPY ! (Line 5 

DEVICE SUBTYPE: 9 ! (Line 6 

DRT: 4 UNIT: 1 ! (Line 7 

256 BLOCK SIZE: 256 (BYTES) ! (Line 8 

MAX EXTENTS: 8 ! (Line 9 

RECLIMIT: 1023 ! (Line 10) 

PHYSCOUNT: ! (Line 11) 

LABEL ADDR: X00201 327630 ! (Line 12) 

ID IS JOE UL ABELS: ! (Line 13) 

1000000000000001 ! (Line 14) 

NUMBER READERS: 1 ! (Line 15) 

RESIDUE: ! (Line 16) 

NUMREC: 1 ! (Line 17) 



128 



AOPTIONS: 

DEVICE TYPE: 
LDEV: 2 
RECORD SIZE: 
EXTENT SIZE: 
RECPTR: 
L0GC0UNT: 
EOF AT: 
FILE CODE: 
PHYSICAL STATUS 
NUMBER WRITERS: 
ERROR NUMBER: 
BLOCK NUMBER: 
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The lines indicated show the following information: 



Line 

1 
2,3 



4,5 



Content 

The filename (IN. VOLLMER . CL I FTON) . 
The f options in effect , including : 
Domain : 



File Type : 



Default file 
Designator : 



Record Format : 



NEW - A new file. 

SYS - System file domain. 

JDB - Job temporary file domain . 

ASCII 
BINARY 

FORMAL - Actual file designator is the same as the for- 
mal file designator. 
$STDIN 
ISTDLIST 
$STDINX 
$NEWPASS 
SOLDPASS 
$NULL 

F - Fixed length. 
V - Variable length. 
U - Undefined length . 
? - Unknown format . 



Carriage Control: NDCCTL - None. 

CCTL - Carriage control character expected. 

File Equation FEQ - : F I LE allowed . 

Option : DEQ - : F I LE not allowed . 

Labeled NOLABEL - Not a labeled tape. 

Tape Option: LABEL - Labeled tape. 



The aoptions in effect, including: 
Access Type : 



Multi -record 
Option : 

Dynamic 
Locking 
Option : 



INPUT - Read access. 

OUTPUT - Write access. 

OUTKEEP - Write -only access, without deleting. 

APPEND - Append access. 

IN/OUT - Input and output access. 

UPDATE - Update access. 

NOMR - Single record access . 
MR - Multirecord access. 

NOLOCK - No locking permitted. 
LQCK - Locking permitted. 
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Exclusive DEF - Default specification. 

Access EXC - Exclusive access allowed. 

Option : SEA - Semi -exclusive access. 

SHR-Sharablefile. 

Buffering: BUF - Automatic Buffering. 

NOBUF - Inhibit buffering. 

Multi -access NDMULTI - Multi-access not allowed. 

Option: MULTI - Intra- job multi -access allowed. 

GMULTI - Inter -job multi -access allowed 
(any job/session process tree). 

Wait WA I T - I/O with wait . 

Option : NOWA I T - I/O without wait . 

Copy NDCOPY - No special treatment of MSG , CIR files. 

Option: COPY - Treat MSG, CIR files as regular variable length 

files. 

6,7 The device type, device subtype, Logical Device Number (LDEV), Device 

Reference Table (DRT), and unit of the device on which the file resides. 
If the file is a spoolfile, the Idev will be "virtual" rather than a physical 
device number. (Refer to Idev under FGETINFD.) 

8 The record and block size of the offending record, in bytes or words as 

noted. 

9 The extent size of the current extent and the maximum number of extents 

allowed this file. 

1 The current record pointer and limit on number of records in the file. 

1 1 The present count of logical and physical records. 

1 2 The locations of the current end-of-f ile and header label of the file. 

13 The file code, name of the file's creator, and number of user -created 

labels . 

1 4 The physical (hardware) status of the device on which the file resides. 

15 "NUMBER WRITERS" is the number of FOPEN calls of the file with some 

type of write access to the file. "NUMBER READERS" is the number of 
FOPEN calls to the file with read access to the file. This is only for message 
files, in all other files it will not appear. 

1 6 The error number and residue ; same as for the abbreviated file information 

display format. 

17 The block number and number of records (NUMREC) for the file. 
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APPENDIX 



B 



MPE intrinsics can be used to alter certain aspects of device operation. Before any of these intrinsics 
can be issued against a device , the devicef ile must be opened with the FQPEN intrinsic (refer to the 
FOPEN discussion in Section II). 

With the FCONTRQL intrinsic, you can: 

• Change terminal speed. 

• Change input echo facility. 

• Enable and disable the system BREAK function. 

• Enable and disable subsystem BREAK requests. 

• Enable and disable parity checking. 

• Enable and disable tape -mode option. 

• Enable and disable the terminal timer. 

• Read the result from the terminal input timer. 

• Define line -termination characters for terminal input. 

Card Reader 

The card reader is a unit record device. The data is read in ASCII mode; that is, two columns are 
converted to ASCII and packed into the left and right byte of one word. If the read request specifies 
80 or more bytes, 80 bytes will be transmitted independent of the data on the card. 

Line Printer 

The line printer is a print and space device (postspace). The prespace operation is simulated by per- 
forming a print operation and then filling the line printer buffer. A carriage control code of JS320 
will append data to the current contents of the line printer buffer, whether prespace or postspace is 
selected. 

To change the mode control settings (pre/post spacing and auto/no -auto page eject) FWRITE is used 
with carriage controls %100 - %103 and %400 - %403. If FWRITE is called with one of these carriage 
controls and count s {count* 1 if imbedded control), then no physical I/O will occur; the only effect is 
changing the mode. 
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Magnetic Tape 

The magnetic tape unit reads and writes undefined -length records in packed binary mode. Each word 
of data is represented by two tape characters. On read requests, the amount of data transferred is the 
lesser of the read request length and the tape record length. An end of tape indication is returned 
whenever a write operation completes with the tape positioned beyond the EOT marker . 

Line Printer and Terminal Carriage Control Codes 

Line printer and terminal carriage control codes are shown in Table 2-5 (refer to Section II, 
FWRITE). All of the Carriage Control Codes shown in Table 2-5 may be used as the value of the 
param parameter of FCONTROL (when controlcode=l) regardless of whether the file is opened with 
CCTL or NOCCTL specified in the FDPEN intrinsic. The device must be nonspooled. When the file is 
opened with CCTL, the Carriage Control Codes may be used via FWRITE either as the value of the 
control parameter, or, when control is specified as 1 , as the first byte of the target array. Carriage 
Control Codes greater than %403 cause an error return with no operation performed. The default 
mode controls are post spacing with automatic page eject. 

End-of-File Indication 

An end-of-file indication is returned by the card reader and tape drivers under conditions specified 
by the initiators of read requests. The types of requests and the end-of-file classes are as follows: 

Type Class of End-Of-File 

A All records that begin with a colon ( : ) . 

B All records that contain, starting in the first byte, :E0D, :E0J, 

: JOB, and :DATA. If the word count is less than 3 or the byte count 
is less than 6 , Type B reads are converted to Type A reads . 

E Hardware-sensed end-of-file. 

In utilizing the card/tape devices as files via the File System , the following types are assigned : 



File Specified 


Type 


SSTDIN 


Type A 


$STDINX 


TypeB 


Dev=CARD/TAPE 


TypeB : 



Type B, if device accepts jobs or data. 

Type E , if device does not accept jobs or data . 

Any subsequent requests to the device after an end-of-file condition is detected are rejected with an 
end-of-file indication, except as described in the next paragraph. 

When reading from an unlabeled tape file, a request encountering a tape mark responds with an end- 
of-file indication, but succeeding requests are allowed to continue reading data past the tape mark. 
Under these conditions , it is the responsibility of the caller to protect against the occurrence of data 
beyond an end-of-file, and to prevent reading off the end of the reel. 
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Terminals 

Refer to the MPE File System Reference Manual (30000-90236) for detailed information on ter- 
minals and terminal characteristics. 

Using the FCARD Intrinsic With an HP 7260A Optical Mark Reader 

The FCARD intrinsic enables you to programmatically control the operation of the HP 7960A Optical 
Mark Reader (OMR). This is achieved through passing a parameter value (recode), corresponding to 
the function of FCARD desired, from a program to FCARD. FCARD returns parameter values to the 
calling program which indicate the success or the cause of failure of execution, the status of the HP 
7260A, the file number of the HP 7260A/terminal file for which the function has been performed 
and the number of columns read at the completion of a read request. 

The program shown in Figure B-l performs the following: 

• Opens the HP 7260A/terminal file. 

• Displays Operator instructions. 

• Temporarily suspends program operation until the HP 7 260 A READY switch is pressed. 

• Reads ten cards in the ASCII reading format. 

• Displays the number of columns read from each card. 

• Examines STATUS for empty input hopper status. 

• Examines output RECODE values for each request. 

• Closes the HP 7260A terminal file. 

Under the label QPENFILE, the program requests that an HP 7260A/terminal file be opened for ac- 
cess and that the file number of this file be returned to the program in the parameter FILENUM by as- 
signing to RECODE a value of 0, and calling FCARD as illustrated. When process control is returned 
from FCARD, the program verifies that the call was successful (RECODE=0) and continues at the label 
D ISP INST. Under this label, Operator instructions are displayed on the ISTDLISTdevice. If the call 
to FCARD was unsuccessful (REC0DE<>0), then the error message "CANNOT OPEN FILE - PROGRAM 
WILL TERMINATE" is displayed, and the program goes to the label FINIS and terminates. 

Under the label RDYWAIT, a display instructing the Operator to press the READY switch is given, and 
the request for a temporary suspension of the program awaiting the depression of the READY switch 
is made by setting RECODE to 4 and calling FCARD as illustrated . The program , upon regaining process 
control, checks for unsuccessful execution of the request (REC0DE<>0). If the execution was unsuc- 
cessful, the program goes to the label FINIS and terminates. The program could also have branched 
to an instruction set to correct or display an error at this point. If the execution was successful, the 
program continues with the next statement, which is under the label READ'. 

Under the label READ', the program requests the reading of ten cards by setting RECODE to 1 and call- 
ing FCARD as illustrated. Upon return of the process control from FCARD, the program checks for an 
unsuccessful execution (REC0DE<>0). If the execution was unsuccessful, the program goes to the label 
READ 'ERR. 
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Under the label READ 'ERR, the program determines the value of RECQDE returned after the read 
request , and initiates corrective action and/or displays an appropriate error message , or terminates it- 
self , depending on the value of RECQDE detected. 

If the execution was successful , the program checks STATUS for an empty input or full output hopper 
condition, and if this status condition is detected, the program goes to the label HOPPERS under which 
corrective steps are initiated. If this status condition is not detected, the program calls the procedure 
DISPCOUNT, which displays the number of columns read from the previous card. After the 
DISPCOUNT procedure is completed, the program goes to the label CLOSE y F. 

Under the label CLOSE 'F, the program requests that the HP 7260A be put in the NOT READY state 
and that the HP 7260A/terminal file be closed by setting RECODE equal to 10 and calling FCARD; and 
by setting RECODE equal to 20 and calling FCARD, respectively. In both cases, the value of RECODE 
returned from FCARD is examined for an indication of successful execution as illustrated in Figure 
B-l. 

ASCII and Column Image Reading Formats 

In the ASCII mode (also called the Hollerith mode), the OMR recognizes 128 -character Hollerith 
codes and transmits one 7 -bit serial ASCII character plus an even parity bit per card column. FCARD 
packs two ASCII characters (two columns of data) into each buffer word in BUFADR. The data from 
the first column of the card is stored in the upper byte of the first word of the buffer , as illustrated 
below : 



Bits 
Word 1 
Word 2 



7 8 



15 



1st column data 


2nd column data 


3rd column data 


4th column data 



In the column image mode, the OMR transmits a 12 -bit data string, representing the twelve rows of 
one card column. FCARD packs the first 12 -bit data string (the first column of data) into the first 
buffer word in BUFADR, as illustrated in the following program example: 



BUFFER WORD 



- 


- 


- 


- 


12 


11 





1 


2 


3 


4 


5 


6 


7 


a 


9 














X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 



COLUMN ROW NO. 
DATA 



12 3 4 



7 8 9 10 11 12 13 14 15 BIT NO. 
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SCONTROL USLINIT 

BEGIN 

INTEGER ARRAY BUFADR (0 : 99) ; 

BYTE ARRAY T00{0:72); 

POINTER HERE; 

INTEGER RECODE, A, I; 

INTRINSIC QUIT, PRINT; 

INTEGER COUNT, FILENUM, STATUS; 

INTRINSIC PRINT'FILE'INFO; 



PROCEDURE DISP 1 COUNT (COUNT) 
INTEGER COUNT; 

BEGIN 

ARRAY OUT(0:ll); 
BYTE ARRAY ROUT(*)»OUT; 
INTRINSIC PRINT, ASCII; 
INTEGER A1.A2; 



MOVE ROUT:="N0. OF COLUMNS READ= "; 
Al:«ASCII(COUNT,10,R0UT(21)) ; 
A2: = -21-A1; 
PRINT(OUT,A2,%401) ; 

END; 

PROCEDURE FCARD(RECODE, FILENUM, BUFADR, COUNT, STATUS) ; 

INTEGER ARRAY BUFADR; 

INTEGER RECODE .FILENUM , COUNT , STATUS ; 

OPTION EXTERNAL; 



@HERE:*<aTOO & LSR(l); 
OPENFILE: 

<<GET FILE NUMBER FOR LOGICAL DEV EQUAL TO THE TERMINALS 

RECODE :«0; 

FCARD (RECODE , F ILENUM , BUFADR , COUNT , STATUS ) ; 

IF RECODE >0 THEN GO DISPINST; 

MOVE TOO:="CANNOT OPEN FILE - PROGRAM WILL TERMINATE"; 

PRINT (HERE, -40,0); 

GO FINIS; 



Figure B- 1 . FCARD Intrinsic Example (1 of 3) 
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DISPINST: 

MOVE T00:=(%15,%12) ; 

PRINT(HERE,-2,0); 

MOVE TOO:="SET THE 7260A FOR CLOCK ON DATA."; 

PRINT (HERE, -32,0); 

MOVE T00:="PUSH IN THE FULL/HALF SWITCH TO ITS FULL POSITION. 

PRINT{HERE,-49,0) ; 

MOVE TOO:="UNMUTE THE TERMINAL."; 

PRINT(HERE,-20,0) ; 

MOVE TOO:="LOAD 30 CLOCK ON DATA CARDS IN THE INPUT HOPPER."; 

PRINT(HERE,-48,0); 

RDYWAIT: 

MOVE TOO: -"NOW, PRESS THE READY SWITCH."; 

PRINT(HERE,-28,0) ; 

REC0DE:=4; 

FCARD ( RECODE , FILENUM , BUFADR , COUNT , STATUS ) ; 

A:=0;I:=0; 

IF RECODE <>0 THEN GO FINIS; 

READ ' : 

DO BEGIN 

RECODE :=1; 

FCARD(RECODE, FILENUM, BUFADR, COUNT, STATUS); 

IF RECODE <> THEN GO READ' ERR; 

IF STATUS = %07 THEN GO HOPPERS; 

DISP'COUNT(COUNT) ; 

I:=I+1; 

END 
UNTIL 1=10; 
GO CLOSET; 

HOPPERS: 

RECODE: =10; <<MAKE BMR NOT READY>> 

FCARD (RECODE, FILENUM, BUFADR, COUNT .STATUS) ; 
IF RECODE <> THEN BEGIN 
A:=A+1; 

IF A<5 THEN GO HOPPERS; 
PRINT'FILE'INFOCFILENUM) ; 
QUIT (RECODE) ; 

END; 
MOVE TOO:="INPUT HOPPER EMPTY OR OUTPUT HOPPER FULL"; 
PRINT(HERE,-40,0) ; 

MOVE TOO:="CORRECT HOPPER CONDITION AND PRESS READY"; 
PRINT(HERE,-40,0) ; 
IF RECODE <> THEN GO FINIS ELSE 
GO READ' ; 



Figure B- 1 . FCARD Intrinsic Example (2 of 3) 
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CLOSE 'F: 

RECODE: =10; <<MAKE CR NOT READY>> 

FCARD(RECODE,FILENUM,BUFADR, COUNT, STATUS); 

IF RECODE <> THEN BEGIN 

I:=I+1; 

IF I < 16 THEN GO CLOSE'F; 

PRINT'FILE'INFO(FILENUM) ; 

END; 
RECODE: =20; 

FCARD ( RECODE , FILENUM , BUFADR , COUNT , STATUS ) ; 
IF RECODE =0 THEN GO FINIS ELSE BEGIN 

MOVE TOO := "UNABLE TO CLOSE THE TERMINAL FILE"; 

PRINT(HERE,33,0); 

GO FINIS; END; 

READ'ERR: 

IF RECODE =8 THEN GO RETRANS; 

IF RECODE =4 THEN BEGIN 

MOVE TOO:="FREAD OR FWRITE ERROR-PROGRAM WILL ABORT"; 

PRINT(HERE,-40,0); 

QUIT (RECODE); END; 

IF RECODE =6 THEN BEGIN 

MOVE TOO:=":EOJ, :EOD, :DATA, OR :JOB FOUND IN INPUT."; 

PRINT(HERE,-42,0); 

MOVE TOO := "CHECK CARD VALIDITY-PROGRAM WILL RESTART"; 

PRINT(HERE,-40,0); 

GO DISPINST; END; 
MOVE TOO:="UNINTERPRETED ERROR-PROGRAM WILL ABORT"; 
PRINT(HERE,-37,0); 
QUIT(RECODE) ; 

RETRANS: 

RECODE: =3; 

FCARD ( RECODE , FILENUM , BUFADR , COUNT , STATUS ) ; 

IF RECODE <> THEN BEGIN 

MOVE TOO —"UNSUCCESSFUL RETRANSMIT-PROGRAM WILL ABORT" 

PRINT(HERE,-42,0) ; 

QUIT (RECODE); END; 

IF STATUS =0 THEN GO READ'; 

MOVE TOO —"UNSUCCESSFUL RETRANSMIT-PROGRAM WILL ABORT"; 
PRINT(HERE,-42,0); 
QUIT(RECODE); 
FINIS: 
END. 



Figure B-l . FCARD Intrinsic Example (3 of 3) 
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DB Pointer, Changing, 2-250 

DB Pointer, Moving, 3-5 

Deactivating 

File-Access Modes, 2- 1 50 

RIO Records, 2-74 



Deadlocks, 3-34 
DEBUG Intrinsic, 2-42 
Declarations 

Intrinsic, 1-2 

Procedure, 1-2 
Declaring Access-Mode Options, 4-38 
Define, Parameters, 2-208 
Deleting 

Extra Data Segment, 3-21 

Inactive Entries From USL File, 2-21 

Processes, 2-194, 3-29 
Determining 

Father Process, 3-35 

PIN of Process Locking Local RIN, 2-200 

Son Process, 3-36 

Source of Activation Call, 2-177 

Source of Process Activation, 3-35 

Status of File Pairs, 2-146 

User Access Mode/ Attributes, 5-12 
Device Characteristics 

Card Reader, B-l 

Line Printer, B-l 

Magnetic Tape, B-2 

Terminals, B-3 
Devices 

Allocation/Classification Of , 4-12 
Directory Space, Adjusting, 2-9 
Disable 

Abort Stack Analysis Facility, 2-237 

Hardware Arithmetic Traps, 2-13 

Software Interrupts, 2-99 

Software Library Trap, 2-266 

System Trap, 2-267 

User Software Arithmetic Trap, 2-262 
Disc Files , 

File Label Information, 2-101 

Opening, 4-20 
Displaying File Information, A- 12 
DLSIZE Intrinsic, 2-43 
DL To DB Area Size, Changing, 5-31 
DMOVIN Intrinsic, 2-45 
DMOVOUT Intrinsic , 2-47 
Domains, File, 4-2 
Drive, Optical Mark Reader, 2-54 
DS Subqueue, 3-6 
Dump Stack to File, 2-243 
Duplicative File Pairs, 2-146 
Dynamic 

Loading, 5-3 

Load/Unload, Library Procedure, 5-2 

Unloading, 5-3 
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Enabling 

Hardware Arithmetic Traps, 2-13 

Software Interrupts, 2-99 

Software Library Trap, 2-266 

Stack Analysis Facility , 2-241 

System Trap, 2-267 

User Software Arithmetic Trap, 2-262 
Enabling/Disabling Traps, 5-37 
End -of -File Indication, B-2 
ENDLOG Intrinsic, 2-49 
Entering 

Non- Privileged Mode, 3-5 

Privileged Mode, 2-180, 3-3 
Error -Check Procedure Writing, 4-33 
Error Messages , Types Of 

ACTIVATE Intrinsic, A- 7 

CREATE Intrinsic, A- 7 

LOADER Error/ War nings , A- 8 

LOCKGLORIN Intrinsic, A- 8 

MYCOMM AND Intrinsic, A- 8 

Run -Time, A- 7 

SUSPEND Intrinsic, A-7 
Errors, Intrinsic Call , 1-5 
ESSubqueue, 3-6 
Executing MPE Commands Programmatically , 

2-26, 5-11 
Expanding Area Between DL and DB, 2-43 
EXP ANDUSLF Intrinsic, 2-51 
Extended Precision Floating Point Trap, 5-39 
Extra Data Segment 

Altering Size Of, 2-11 

Changing Size Of, 3-22 

Creating, 2-171, 3-10 

Deleting, 3-21 

Releasing, 2-144 

Transferring Data From Stack, 
2-47, 3-21 

Transferring Data To Stack, 
2-45, 3-21 



FATHER Intrinsic, 2-53 

Father Process, Determining, 3-35 

FCARD Intrinsic, 2-54 

Using With Optical Mark Reader, B-3 



FCHECK Intrinsic, 2-58 
FCLOSE Intrinsic, 2-65 
FCONTROL Intrinsic, 2-68 
FDELETE Intrinsic, 2-74 
FDEVICECONTROL Intrinsic, 2-75 
FERRMSG Intrinsic, 2-84, 4-33 
FFILEINFO Intrinsic, 2-85 
FGETINFO Intrinsic, 2-88 
File Designators , Parsing/Validating , 

2-130,4-15 
File Device Relationships, 4-2 
File Domains, 4-2 
File Information, Displaying, A- 12 
File System Error -Check Procedure, 4-33 
Files 

Accessing, 2-111 
Closing, 2-65, 4-28 

Closing New File as Permanent File, 4-31 
Closing New File as Temporary File, 4-28 
Device Relationships, 4-2 
Dynamically Lock , 2-104 
How to Use, 4-5 
Non -Shar able Devices, 4-4 
Opening, 4-3 

Opening New Disc Files ,4-17 
Opening On Device Other Than Disc, 4-22 
Renaming, 2-148 
FINDJCW Intrinsic, 2-96 
FINTEXIT Intrinsic ,2-98 
FINTSTATE Intrinsic ,2-99 
FLABELINFO Intrinsic ,2-101 
FLOCK Intrinsic, 2-104 
FLUSHLOG Intrinsic , 2-106 
FMTCALENDAR Intrinsic, 2-108 
FMTCLOCK Intrinsic , 2-109 
FMTDATE Intrinsic, 2-110 
FOPEN Intrinsic, 2-111 
Foptions Bit Summary, 2-88 
Formatting Calendar Dates/Time, 

2-108, 5-52 
Formatting Command Parameters, 5-5 
FPARSE Intrinsic, 2-130 
FPOINT Intrinsic, 2-133 
FREAD Intrinsic ,2-135 

Using With $STDIN/$STDLIST, 4-23 
FREADBACK WARD Intrinsic, 2-137 
FREADDIR Intrinsic , 2-139 
FREADL ABEL Intrinsic. 2-141 
FREADSEEK Intrinsic, 2-143 
FREEDSEG Intrinsic , 2-144 
Freeing Local RINs, 2-145, 3-45 
FREELOCRIN Intrinsic, 2-145 



1-3 



INDEX (Continued) 



FRELATE Intrinsic, 2-146 
FRENAME Intrinsic, 2-148 
FSETMODE Intrinsic, 2-150 
FSPACE Intrinsic, 2-153 
Functional Return , 2-2 
FUNLOCK Intrinsic, 2-155 
FUPDATE Intrinsic, 2-156 
FWRITE Intrinsic, 2-158 

Using With $STDIN/$STDLIST, 
FWRITEDIR Intrinsic, 2-164 
FWRITELABEL Intrinsic, 2-166 
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GENMESSAGE Intrinsic, 2-167 
GETDSEG Intrinsic ,2-171 
GETINFO Intrinsic, 2-173 
GETJCW Intrinsic, 2-175 
GETLOCRIN Intrinsic, 2-176 
GETORIGIN Intrinsic ,2-177 
GETPRIORITY Intrinsic, 2-178 
GETPRIVMODE Intrinsic ,2-180 
GETPROCID Intrinsic ,2-181 
GETPROCINFO Intrinsic, 2-182 
GETUSERMODE Intrinsic, 2-184 
Global RINs 

Acquiring, 3-38 

Inter -Job Level, 3-38 

Locking, 2-196 

Locking/Unlocking ,3-39 

Releasing, 3-39 

Unlocking, 2-254 
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Hand -Shaking Arrangement, 3- 
How to Use Files, 4-5 
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Identifying Job/Session with JOBINFO, 5-14 
Identifying Local RIN Owners, 3-44 
Implementing Intrinsic Calls, 1-2 
Initialize USL File to Empty State, 2-185 
Initiate Completion of I/O Request , 2-186 
Initiate Session on Specified Terminal, 2-245 



INITUSLF Intrinsic ,2-185 

Interactive File Pairs, 2-146 

Inter- Job Level Global RINs, 3-38 

Internal Operations For File Accessing, 4-5 

Interprocess Communication , 3-24, 3-31, 5-54 

Interprocess Local Level RINs, 3-43 

Intrinsics 

Call Errors, 1-5 

Calling, 1-1 

Calling From SPL, 1-1 

Calls, Implementing, 1-2 

Declarations, 1-2 

Functions, 1-7 

Names, 2-1 

Numbers, 2-1 

Procedure Declarations, 1-2 

Time and Date, 5-49 
Intrinsics, List Of 

ABORTSESS, 2-5 

ACTIVATE, 2-7 

ADJUSTUSLF, 2-9 

ALTDSEG, 2-11 

ARITRAP, 2-13 

ASCII, 2-14 

BEGINLOG, 2-16 

BINARY, 2-18 

CALENDAR, 2-19 

CAUSEBREAK, 2-20 

CLEANUSL, 2-21 

CLOCK, 2-23 

CLOSELOG, 2-24 

COMMAND, 2-26 

CREATE, 2-27 

CREATEPROCESS, 2-32 

CTRANSLATE, 2-36 

DASCII, 2-38 

DATELINE, 2-40 

DBINARY, 2-41 

DEBUG, 2-42 

DLSIZE, 2-43 

DMOVIN, 2-45 

DMOVOUT, 2-47 

ENDLOG, 2-49 

EXPANDUSLF, 2-51 

FATHER, 2-53 

FCARD, 2-54 

FCHECK, 2-58 

FCLOSE, 2-65 

FCONTROL, 2-68 

FDELETE, 2-74 

FDEVICECONTROL, 2-75 

FERRMSG, 2-84, 4-33 
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FFILEINFO, 2-85 
FGETINFO, 2-88 
FINDJCW, 2-96 
FINTEXIT, 2-98 
FINTSTATE, 2-99 
FLABELINFO, 2-101 
FLOCK, 2-104 
FLUSHLOG, 2-106 
FMTCALENDAR, 2-108 
FMTCLOCK, 2-109 
FMTDATE, 2-110 
FOPEN, 2-111 
FPARSE, 2-130 
FPOINT, 2-133 
FREAD, 2-135 
FREADBACKWARD ,2-137 
FREADDIR, 2-139 
FREADLABEL, 2-141 
FREADSEEK, 2-143 
FREEDSEG, 2-144 
FREELOCRIN, 2-145 
FRELATE, 2-146 
FRENAME, 2-148 
FSETMODE, 2-150 
FSPACE, 2-153 
FUNLOCK, 2-155 
FUPDATE, 2-156 
FWRITE, 2-158 
FWRITEDIR, 2-164 
FWRITELABEL, 2-166 
GENMESSAGE, 2-167 
GETDSEG, 2-171 
GETINFO, 2-173 
GETJCW, 2-175 
GETLOCRIN, 2-176 
GETORIGIN, 2-177 
GETPRIORITY, 2-178 
GETPRIVMODE, 2-180 
GETPROCID, 2-181 
GETPROCINFO, 2-182 
GETUSERMODE ,2-184 
INITUSLF, 2-185 
IODONTWAIT, 2-186 
IOWAIT, 2-188, 4-35 
JOBINFO, 2-190, 5-14 
KILL, 2-194 
LOADPROC, 2-195 
LOCKGLORIN, 2-196 
LOCKLOCRIN, 2-198 
LOCRINOWNER, 2-200 
LOGINFO, 2-201 
LOGSTATUS, 2-204 



MAIL, 2-206 
MYCOMMAND, 2-208 
OPENLOG, 2-211 
PAUSE, 2-213 
PRINT, 2-214 
PRINTFILEINFO, 2-216 
PRINTOP, 2-217 
PRINTOPREPLY, 2-218 
PROCINFO, 2-220 
PROCTIME, 2-223 
PTAPE, 2-224 
PUTJCW, 2-226 
QUIT, 2-228 
QUITPROG, 2-229 
READ, 2-230 
READX, 2-232 
RECEIVEMAIL, 2-234 
RESETCONTROL, 2-236 
RESETDUMP, 2-237 
SEARCH, 2-238 
SENDMAIL, 2-239 
SETDUMP, 2-241 
SETJCW, 2-242 
STACKDUMP, 2-243 
STARTSESS, 2-245 
SUSPEND, 2-248 
SWITCHDB, 2-250 
TERMINATE, 2-251 
TIMER, 2-252 
UNLOADPROC, 2-253 
UNLOCKGLORIN, 2-254 
UNLOCKLOCRIN, 2-255 
WHO, 2-256 
WRITELOG, 2-260 
XARITRAP, 2-262 
XCONTRAP, 2-264 
XLIBTRAP, 2-266 
XSYSTRAP, 2-267 
ZSIZE, 2-268 
Invoking DEBUG Facility, 2-42 
IODONTWAIT Intrinsic, 2,186 
IOWAIT Intrinsic, 2-188, 4-35 



JCWs (See Job Control Words) 
Job Control Words (JCWs), 5-53 
System -Defined, 5-53 
User -Defined, 5-53 
Value in JCW Table, 2-226 
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Job, Identifying With JOBINFO, 5-14 

JOBINFO, 2-190 

Job/Session 

Access to Related Information, 2-190 
Input Devices, Reading Input From, 5-23 
I/O Devices, Transmitting Programs, 5-23 
List Device, Writing Output To, 5-25 

Job Temporary File Directory, 4-9 
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Logging File, 

Information About , 2-201 

Uses For, 3-51 
Logging, User, 3-45 
Logging, User Procedures, 3-50 
LOGINFO Intrinsic ,2-201 
LOGSTATUS Intrinsic, 2-204 



M 



KILL Intrinsic, 2-194 



Languages, Calling Intrinsics From, 1-4 
Library Trap, 5-42 
Library Procedures 

Dynamic Loading, 2-195, 5-3 

Dynamic Loading/Unloading , 5-2 

Dynamic Unloading , 2-253, 5-3 
Linear Subqueue , 3-6 
Line Printer, B-l 

Line Printer Carriage -Control Codes, B-2 
LOADER Error /Warning Messages, A- 9 
Loading, Dynamic, 5-3 
Load Library Procedure Dynamically, 2-195 
LOADPROC Intrinsic, 2-195 
Local RINs 

Acquiring, 2-176 

Freeing, 3-45 

Identifying Owners, 3-44 

Interprocess Level ,3-43 

Locking, 2-198 

Locking/Unlocking ,3-43 

Unlocking, 2-255 
LOCKGLORIN Intrinsic, 2-196 
Locking 

Files, Dynamically, 2-104 

Global RINs, 2-196, 3-39 

Local RINs, 2-198, 3-43 
LOCKLOCRIN Intrinsic, 2-198 
LOCRINOWNER Intrinsic, 2-200 
Logging Facility 

Close Access To, 2-24 

Provide Access To, 2-211 



Magnetic Tape, B-2 
Mail 

Receiving, 2-234, 3-33 

Sending, 2-239, 3-32 
Mailbox, 3-31 
MAIL Intrinsic , 2-206 
Mailbox, Testing Status Of , 2-206, 3-32 
MAKECAT Program, 5-57 
Marking 

End of Logging Transaction, 2-49 

Start of User Logging Transaction, 2-16 
Master Queue, 3-5 
Message Catalog , 5-56 
Message Facility , MPE, 5-56 
Messages 

Intrinsic Error , A- 5 

LOADER Err or/ Warning, A- 8 

Operator, A- 10, A- 11 

Run-Time, A-l, A-7 

System, A- 11 

System Failure , A- 1 

System Operator, A-l , A-l 1 

User, A- 10 
Mnemonics, Definitions, 2-1 
Moving 

DB Pointer, 3-5 

Physical Record Pointer, 2-153 

Record From Disc File to Buffer, 2-143 

User Logging Memory Buffer to 
Logging File, 2-106 
MPE Commands , Executing 

Programmatically , 2-26, 5-11 
MPE Message Facility, 5-56 
Multi-Access (MULTI), 4-2 
Multiple Resource Identification Number ,1-8 
MYCOMM AND Intrinsic, 2-208 
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New Disc Files, Opening ,4-17 
Non-Sharable Devices 

Accessing, 4-2 

Files On, 4-4 
Non -Privileged Mode, Entering, 3-5 



O 



Obtaining 

Calendar Date, 5-52 

Current Time ,5-50 

Process Run Time, 5-52 

System Timer Information, 5-50 
Octal Values, 2-56 
Opening 

Files, 4-3 

Files On Devices Other Than Disc, 4-22 

New Disc Files, 4-17 

Old Disc Files, 4-20 

$STDIN, 4-25 

SSTDLIST, 4-25 
OPENLOG Intrinsic, 2-21 1 
Operator Console , 5-26 
Operator Messages, A- 10, A-l 1 
Optical Mark Reader, 2-54, B- 3 
Optional Capabilities , 1-7 

Create Volumes, 1-9 

Data -Segment Management, 1-8 

Multiple Resource Identification No., 1- 

Privileged Mode ,1-8 

Process Handling ,1-8 

Programmatic Sessions ,1-8 

User Logging ,1-8 

Volume Set Usage, 1 -9 
Optional Parameters ,1-3 



Parameters 

Definition, 2-3 

User-Defined Command , 2-208 

WithGENMESSAGE, 5-59 

Parsing File Designators, 2-1 30, 4-15 

PAUSE Intrinsic, 2-213 

Performing Control Operations, 2-75 



Permanently Privileged Programs, 3-1 
PRINT Intrinsic, 2-214 
PRINTFILEINFO Intrinsic, 2-216 
Printing 

Character Strings , 2-214 

File Information , 2-216 

On System Console, 2-217 

Reply, From System Console, 2-218 
PRINTOP Intrinsic, 2-217 
PRINTOPREPLY Intrinsic, 2-218 
Priority Classes, 3-6 
Privileged Mode 

Capability, 1-8, 3-1 

Entering, 2-180, 3-3 
Procedure Declarations ,1-2 
Process Break , Requesting , 5-27 
Processes, 3-23 

Aborting, 2-228, 5-28 

Accumulated CPU Time Of, 2-223 

Activating, 2-7 

Active/Suspended Process Substates, 3-24 

Changing Priority Of , 2- 1 78 

Creating, 2-27 

Creating/ Activating, 3-24 

Deleting, 3-29 

Determining Source of Activation, 3-35 

Organization Of User , 3-23 

Rescheduling, 3-34 

Scheduling, 3-5 

Suspending, 2-248, 3-29 

Terminating, 2-251, 5-27 
Process Handling Capability, 1-8, 3-22 
Process Identification Number (PIN), 3-23 
Process Priority 

Changing, 2-178 

Determining, 3-36 
Process Run Time, Obtaining, 5-52 
Process State , Determining, 3-36 
PROCINFO Intrinsic, 2-220 
PROCTIME Intrinsic, 2-223 
Programs 

Aborting, 5-28 

Permanently Privileged ,3-1 

Temporarily Privileged ,3-2 
Programmatic Execution Of Commands, 5-11 
Provide Data on Open User Logging File, 2-204 
Providing Control Operations to Devices, 2-75 
PT APE Intrinsic, 2 --224 
PUT JCW Intrinsic, 2-226 
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QUIT Intrinsic, 2-228 
QUITPROG Intrinsic, 2-229 



READ Intrinsic, 2-230 
Reading 

Disc File to User Data Stack, 2-1 39 

Input From Job Input Device, 5-23 

Input From Session Input Device, 5-23 

Logical Record, 2-135 

Logical Record Backward, 2-1 37 

User File Label, 2-141 
Reading ASCII String 

From SSTDIN to Array, 2-230 

From SSTDINX to Array, 2-232 
READX Intrinsic, 2-232 
Receive Mail From Other Process, 2-234 
RECEIVEMAIL Intrinsic ,2-234 
Receiving Mail ,3-33 
Release Extra Data Segment, 2-144 
Releasing Global RINs, 3-39 
Renaming File , 2-148 
Requesting 

File Information , 2-88 

File Input/Output Error Data, 2-58 

PIN of Father Process, 2-53 

PIN of Son Process, 2-181 

Process Break, 5-27 

Status of Father/Son Process, 2-182 
Required Capabilities, 2-3 
Required Parameters, 1-3 
Rescheduling Processes , 2-178, 3-34 
RESETCONTROL Intrinsic, 2-236 
RESETDUMP Intrinsic, 2-237 
Reset , Terminal to Accept 

CONTROL-Y Signal, 2-236 
Resource Identification Numbers 

(See RINs) 
Resource Management, 3-37 
Resources, 3-37 
Retrieve 

Info String From :RUN Command, 2-173 

Parm Value From CREATEPROCESS 
Intrinsic, 2-173 



Returns 

Actual System-Timer Time, 2-23 

Calendar Date, 2-19 

Current Date/Time Information, 2-40 

FCHECK Error Number Message, 2-84 

File Label Data From Disc File, 2-101 

From User Interrupt Procedure, 2-98 

Process CPU Time, 2-223 

System Timer, 2-252 

To Non -Privileged Mode , 2-184 

To Privileged Mode, 2-1 80 

User Information, 2-256 

User Logging File Information, 2-204 

Value of System-Defined JCW, 2-175 

RINs, 3-37 

Acquiring Local, 3-43 
Freeing Local, 2-145, 3-45 
Identifying Local Owners, 3-44 
Interprocess Local Level , 3-43 
Locking/Unlocking Local, 3-43 

Run -Time Messages, A-l 



Scheduling Processes, 3-5 
Searching 

Arrays, 5-4 

Arrays for Specified Entry, 2-238 

Job Control Word Table, 2-96 
SEARCH Intrinsic, 2-238 
Send Mail to Other Process, 2-239 
Sending Mail, 3-32 
SENDM AIL Intrinsic, 2-239 
Sessions 

Aborting, 2-5 

Identifying with JOBINFO, 5-14 

In BREAK Mode, 2-20 
Set 

Bits in System JCW, 2-242 

Logical Record Pointer, 2-133 

System JCW Bits, 2-242 
SETDUMP Intrinsic, 2-241 
SETJCW Intrinsic, 2-242 
Son Process 

Deleting, 2-194 

Determining, 3-36 
Special Considerations, 2-3 
SPL, Calling Intrinsics From, 1-1 
Split -Stack Operations, 2-4 
ST ACKDUMP Intrinsic, 2-243 
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Stack Sizes, Changing, 5-30 

Standard Traps, 5-39 

STARTSESS Intrinsic, 2-245 

Subqueue Priority Classes, 3-6 

Suspending 

Calling Process, 2-213, 5-26 
Processes, 2-248, 3-29 

SUSPEND Intrinsic, 2-248 

Suspended Process Substates, 3-24 

SWITCHDB Intrinsic, 2-250 

Syntax Description , 2-1 

System Console 

Messages, A-l 

Requesting a Reply From, 5-26 

Writing Output To, 5-26 

System Failure Messages, A-l 

System Messages , A- 1 1 

System Operator Messages , A- 1 , A- 1 

System Timer, Obtaining Data From, 
2-23, 2-252, 5-50 

System Trap, 5-44 



Temporarily Privileged Programs, 3-2 
Terminal Carriage -Control Codes, B-2 
TERMINATE Intrinsic, 2-251 
Terminating a Process, 2-251 , 5-27 
Testing Mailbox Status, 2-194, 3-32 
Time and Date Intrinsics, 5-49 
Time Information , Formatting , 

2-109, 2-110, 5-52 
Time Of Day, 2-109, 2-110, 5-50 
TIMER Intrinsic, 2-252 
Transferring Data 

From Extra Data Segment to Stack, 3-21 

From Stack to Extra Data Segment, 3-21 
Translating Characters With 

CTRANSLATE Intrinsic, 2-36, 5-22 
Transmitting Program Input/Output 

From Job/Session Devices, 5-23 
Traps, 1-6 

Arithmetic, 5-38 

Commercial Instruction , 5-40 

CONTROL-Y, 5-46 

Disabling/Enabling ,5-37 

Extended Precision Floating Point, 5-39 

Library, 5-42 

Standard, 5-39 

System, 5-44 



U 



Unloading, Dynamic, 5-3 

Unloading Library Procedure, 2-253 

UNLOADPROC Intrinsic, 2-253 

Unlocking 

Files Dynamically, 2-1 55 
Global RINs, 2-254, 3-39 
Local RINs, 2-255, 3-43 

UNLOCKGLORIN Intrinsic ,2-254 

UNLOCKLOCRIN Intrinsic, 2-255 

User Access Mode, Determining, 5-12 

User Attributes, Determining, 5-12 

User -Defined Job Control Words, 5-55 

User Logging ,3-45 
Capability, 1-8 

Flush Memory Buffer Of, 2-106 
How It Works, 3-46 
Mark Beginning of Transaction, 2-16 
Mark End of Transaction, 2-49 
Procedures, 3-50 

User Messages, A- 10 

User Processes, Organization Of, 3-23 

Uses For Log File, 3-51 

Using Files, 4-5 

USL Files 

Directory Space , Adjusting, 2-9 
Inactive Entries , Deleting, 2-21 
Initializing To Empty State, 2-185 
Length Of, Changing, 2-51 

Utility Functions, MPE, 5-1 



Validating File Designators , 2-130, 4- 
Volume Set Usage Capability, 1-9 
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WHO Intrinsic, 2-256 
WRITELOG Intrinsic ,2-260 
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Writing XLIBTRAP Intrinsic, 2-266 

File System Error-Check Procedure ,4-33 XSYSTRAP Intrinsic ,2-267 
Logical Record In Disc File, 2-156 ZSIZE Intrinsic, 2-268 

Logical Record/User Stack Z To DB Area Size, Changing, 2-268, 5-37 

To Disc File, 2-164 
Logical Record to File, 2-1 58 

Record to Logging File, 2-260 $ 

User File Label, 2-166 
Writing Output To 

Job/Session List Device ,5-25 SSTDIN 

System Console ,5-26 Assigning ,2-32 

System Console/Request A Reply, 5-26 Opening, 4-25 

Using FREAD/FWRITE With ,4-23 
SSTDLIST 
XYZ Assigning, 2-32 

Opening, 4-25 

Using FREAD/FWRITE With, 4-23 
XARITRAP Intrinsic, 2-262 
XCONTRAP Intrinsic, 2-264 
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